phoenixclaw

PhoenixClaw: Zero-Tag Passive Journaling

PhoenixClaw automatically distills daily conversations into meaningful reflections using semantic intelligence.

Automatically identifies journal-worthy moments, patterns, and growth opportunities.

🛠️ Core Workflow

> [!critical] MANDATORY: Complete Workflow Execution

> This 9-step workflow MUST be executed in full regardless of invocation method:

> - Cron execution (10 PM nightly)

> - Manual invocation ("Show me my journal", "Generate today's journal", etc.)

> - Regeneration requests ("Regenerate my journal", "Update today's entry")

>

> Never skip steps. Partial execution causes:

> - Missing images (session logs not scanned)

> - Missing finance data (Ledger plugin not triggered)

> - Incomplete journals (plugins not executed)

PhoenixClaw follows a structured pipeline to ensure consistency and depth:

1. User Configuration: Check for ~/.phoenixclaw/config.yaml. If missing, initiate the onboarding flow defined in references/user-config.md.

2. Context Retrieval:

- Scan memory files (NEW): Read memory/YYYY-MM-DD.md and memory/YYYY-MM-DD-*.md files for manually recorded daily reflections. These files contain personal thoughts, emotions, and context that users explicitly ask the AI to remember via commands like "记一下" (remember this). CRITICAL: Do not skip these files - they contain explicit user reflections that session logs may miss.

- Scan session logs: Call memory_get for the current day's memory, then CRITICAL: Scan ALL raw session logs and filter by message timestamp. Session files are often split across multiple files. Do NOT classify images by session file mtime:

      # Read all session logs from both OpenClaw locations, then filter by per-message timestamp

      # Use timezone-aware epoch range to avoid UTC/local-day mismatches.
      TARGET_DAY="$(date +%Y-%m-%d)"
      TARGET_TZ="${TARGET_TZ:-Asia/Shanghai}"
      read START_EPOCH END_EPOCH < <(
        python3 - <<'PY' "$TARGET_DAY" "$TARGET_TZ"
from datetime import datetime, timedelta
from zoneinfo import ZoneInfo
import sys

day, tz = sys.argv[1], sys.argv[2]
start = datetime.strptime(day, "%Y-%m-%d").replace(tzinfo=ZoneInfo(tz))
end = start + timedelta(days=1)
print(int(start.timestamp()), int(end.timestamp()))
PY
      )

      for dir in "$HOME/.openclaw/sessions" "$HOME/.agent/sessions"; do
        [ -d "$dir" ] || continue
        find "$dir" -name "*.jsonl" -print0
      done |
        xargs -0 jq -cr --argjson start "$START_EPOCH" --argjson end "$END_EPOCH" '
          (.timestamp // .created_at // empty) as $ts
          | ($ts | fromdateiso8601?) as $epoch
          | select($epoch != null and $epoch >= $start and $epoch < $end)
        '
      

Read all matching files regardless of their numeric naming (e.g., file_22, file_23 may be earlier in name but still contain today's messages).

- EXTRACT IMAGES FROM SESSION LOGS: Session logs contain type: "image" entries with file paths. You MUST:

1. Find all image entries (e.g., "type":"image")

2. Keep only entries where message timestamp is in the target date range

3. Extract the file_path or url fields

4. Copy files into assets/YYYY-MM-DD/

5. Rename with descriptive names when possible

- Why session logs are mandatory: memory_get returns text only. Image metadata, photo references, and media attachments are only available in session logs. Skipping session logs = missing all photos.

- Activity signal quality: Do not treat heartbeat/cron system noise as user activity. Extract user/assistant conversational content and media events first, then classify moments.

- FILTER HEARTBEAT MESSAGES (CRITICAL): Session logs contain system heartbeat messages that MUST be excluded from journaling. When scanning messages, SKIP any message matching these criteria:

1. User heartbeat prompts: Messages containing "Read HEARTBEAT.md" AND "reply HEARTBEAT_OK"

2. Assistant heartbeat responses: Messages containing ONLY "HEARTBEAT_OK" (with optional leading/trailing whitespace)

3. Cron system messages: Messages with role "system" or "cron" containing job execution summaries (e.g., "Cron job completed", "A cron job")

Example jq filter to exclude heartbeats:

      # Exclude heartbeat messages

      | select(
          (.message.content? | type == "array" and 
            (.message.content | map(.text?) | join("") | 
              test("Read HEARTBEAT\.md"; "i") | not))
          and
          (.message.content? | type == "array" and 
            (.message.content | map(.text?) | join("") | 
              test("^\\s*HEARTBEAT_OK\\s*$"; "i") | not))
        )
      

- Edge case - Midnight boundary: For late-night activity that spans midnight, expand the timestamp range to include spillover windows (for example, previous day 23:00-24:00) and still filter per-message by timestamp.

- Merge sources: Combine content from both memory files and session logs. Memory files capture explicit user reflections; session logs capture conversational flow and media. Use both to build complete context.

- Fallback: If memory is sparse, reconstruct context from session logs, then update memory so future runs use the enriched memory. Incorporate historical context via memory_search (skip if embeddings unavailable)

3. Moment Identification: Identify "journal-worthy" content: critical decisions, emotional shifts, milestones, or shared media. See references/media-handling.md for photo processing. This step generates the moments data structure that plugins depend on.

Image Processing (CRITICAL):

- For each extracted image, generate descriptive alt-text via Vision Analysis

- Categorize images (food, selfie, screenshot, document, etc.)

Filter Finance Screenshots (NEW):

Payment screenshots (WeChat Pay, Alipay, etc.) should NOT be included in the journal narrative. These are tool images, not life moments.

Detection criteria (check any):

1. OCR keywords: "支付成功", "支付完成", "微信支付", "支付宝", "订单号", "交易单号", "¥" + amount

2. Context clues: Image sent with nearby text containing "记账", "支付", "付款", "转账"

3. Visual patterns: Standard payment app UI layouts (green WeChat, blue Alipay)

Handling rules:

- Mark as finance_screenshot type

- Route to Ledger plugin (if enabled) for transaction recording

- EXCLUDE from journal main narrative unless explicitly described as part of a life moment (e.g., "今天请朋友吃饭" with payment screenshot)

- Never include raw payment screenshots in daily journal images section

- Match images to moments (e.g., breakfast photo → breakfast moment)

- Store image metadata with moments for journal embedding

4. Pattern Recognition: Detect recurring themes, mood fluctuations, and energy levels. Map these to growth opportunities using references/skill-recommendations.md.

5. Plugin Execution: Execute all registered plugins at their declared hook points. See references/plugin-protocol.md for the complete plugin lifecycle:

- pre-analysis → before conversation analysis

- post-moment-analysis → Ledger and other primary plugins execute here

- post-pattern-analysis → after patterns detected

- journal-generation → plugins inject custom sections

- post-journal → after journal complete

6. Journal Generation: Synthesize the day's events into a beautiful Markdown file using assets/daily-template.md. Follow the visual guidelines in references/visual-design.md. Include all plugin-generated sections at their declared section_order positions.

- Embed curated images only, not every image. Prioritize highlights and moments.

- Route finance screenshots to Ledger sections (receipts, invoices, transaction proofs).

- Use Obsidian format from references/media-handling.md with descriptive captions.

- Generate image links from filesystem truth: compute the image path relative to the current journal file directory. Never output absolute paths.

- Do not hardcode path depth (../ or ../../): calculate dynamically from daily_file_path and image_path.

- Use copied filename as source of truth: if asset file is image_124917_2.jpg, the link must reference that exact filename.

7. Timeline Integration: If significant events occurred, append them to the master index in timeline.md using the format from assets/timeline-template.md and references/obsidian-format.md.

8. Growth Mapping: Update growth-map.md (based on assets/growth-map-template.md) if new behavioral patterns or skill interests are detected.

9. Profile Evolution: Update the long-term user profile (profile.md) to reflect the latest observations on values, goals, and personality traits. See references/profile-evolution.md and assets/profile-template.md.

⏰ Cron & Passive Operation

PhoenixClaw is designed to run without user intervention. It utilizes OpenClaw's built-in cron system to trigger its analysis daily at 10:00 PM local time (0 22 * * *).

• -Setup details can be found in references/cron-setup.md.
• -Mode: Primarily Passive. The AI proactively summarizes the day's activities without being asked.

Rolling Journal Window (NEW)

To solve the 22:00-24:00 content loss issue, PhoenixClaw now supports a rolling journal window mechanism:

Problem: Fixed 24-hour window (00:00-22:00) misses content between 22:00-24:00 when journal is generated at 22:00. Solution: scripts/rolling-journal.js scans from last journal time → now instead of fixed daily boundaries. Features:

• -Configurable schedule hour (default: 22:00, customizable via ~/.phoenixclaw/config.yaml)
• -Rolling window: No content loss even if generation time varies
• -Backward compatible with existing late-night-supplement.js

Configuration (~/.phoenixclaw/config.yaml):

schedule:
  hour: 22        # Journal generation time
  minute: 0
  rolling_window: true   # Enable rolling window (recommended)

Usage:

Default: generate from last journal to now
node scripts/rolling-journal.js

Specific date
node scripts/rolling-journal.js 2026-02-12

💬 Explicit Triggers

While passive by design, users can interact with PhoenixClaw directly using these phrases:

• -*"Show me my journal for today/yesterday."*
• -*"What did I accomplish today?"*
• -*"Analyze my mood patterns over the last week."*
• -*"Generate my weekly/monthly summary."*
• -*"How am I doing on my personal goals?"*
• -*"Regenerate my journal."* / *"重新生成日记"*

> [!warning] Manual Invocation = Full Pipeline

> When users request journal generation/regeneration, you MUST execute the complete 9-step Core Workflow above. This ensures:

> - Photos are included (via session log scanning)

> - Ledger plugin runs (via post-moment-analysis hook)

> - All plugins execute (at their respective hook points)

>

> Common mistakes to avoid:

> - ❌ Only calling memory_get (misses photos)

> - ❌ Skipping moment identification (plugins never trigger)

> - ❌ Generating journal directly without plugin sections

📚 Documentation Reference

References (references/)

• -user-config.md: Initial onboarding and persistence settings.
• -cron-setup.md: Technical configuration for nightly automation.
• -plugin-protocol.md: Plugin architecture, hook points, and integration protocol.
• -media-handling.md: Strategies for extracting meaning from photos and rich media.
• -session-day-audit.js: Diagnostic utility for verifying target-day message coverage across session logs.
• -visual-design.md: Layout principles for readability and aesthetics.
• -obsidian-format.md: Ensuring compatibility with Obsidian and other PKM tools.
• -profile-evolution.md: How the system maintains a long-term user identity.
• -skill-recommendations.md: Logic for suggesting new skills based on journal insights.

Assets (assets/)

• -daily-template.md: The blueprint for daily journal entries.
• -weekly-template.md: The blueprint for high-level weekly summaries.
• -profile-template.md: Structure for the profile.md persistent identity file.
• -timeline-template.md: Structure for the timeline.md chronological index.
• -growth-map-template.md: Structure for the growth-map.md thematic index.

---