opc-journal

Version: 2.5.2
Type: Single CLI-style Skill
Status: Active

A unified CLI entrypoint for journaling, pattern analysis, milestone detection, insights, and task tracking.

Commands

Architecture

Directory Structure

opc-journal/
├── scripts/
│   ├── main.py           # CLI entry point
│   └── commands/
│       ├── init.py       # Initialize journal with charter
│       ├── record.py     # Append entries with auto ID generation
│       ├── search.py     # Full-text local search
│       ├── export.py     # Markdown/JSON export
│       ├── analyze.py    # Structural signal + keyword fragment extraction
│       ├── milestones.py # Milestone candidate detection
│       ├── insights.py   # Context assembly for LLM interpretation
│       ├── task.py       # Single task creation (persistent)
│       ├── batch_task.py # Bulk task creation
│       ├── status.py     # Statistics and streak calculation
│       ├── delete.py     # Entry removal (requires --force)
│       ├── archive.py    # Backup and clear operations (requires --force)
│       ├── update_meta.py# Metadata and language updates
│       └── _meta.py      # Meta helpers with file locking
├── utils/
│   ├── storage.py        # File I/O with path sanitization
│   ├── parsing.py        # Entry block splitting/joining
│   ├── task_storage.py   # Task CRUD with fcntl locking
│   └── timezone.py       # Asia/Shanghai timezone utilities
├── tests/                # 57 pytest test cases
└── config.yml            # Skill metadata

Data Flow

User Input → main.py → Command Router → Command Module → Storage Utils → Local Files
                                              ↓
                                         Return JSON {status, result, message}

All commands follow a uniform return pattern:

• status: "success" or "error"
• result: Structured data (dict, list, or None)
• message: Human-readable description

Security Model

LLM-First Design

This skill delegates interpretation to the caller (LLM) while providing structured extraction:

Key principle: The skill extracts patterns but never draws conclusions about the user's mental state.

Concurrency

• Single-user optimized: File locking prevents corruption but is not designed for high-concurrency multi-user scenarios
• POSIX only: Uses fcntl (not available on Windows)
• Atomic writes: Metadata writes use flock(LOCK_EX) + fsync() + flock(LOCK_UN)

Storage Format

Entry Block Format:

---
type: entry
entry_id: JE-20260413-A1B2C3
date: 13-04-26
day: 1
emotion: excited
language: en
---

Your entry content here.

File Organization:

• memory/DD-MM-YY.md: Daily entry files
• journal_meta.json: Goals, language, total count
• tasks.json: Persistent task list
• archive/YYYYMMDD-HHMMSS/: Timestamped backups

Development Notes

• analyze reads dreams.md and memory/*.md and returns structural signals + keyword fragments for the caller (LLM) to interpret dynamically. Structural signals are purely quantitative (punctuation counts, caps, etc.). Keyword fragments use minimal regex patterns for common action/challenge/achievement words, but no emotional interpretation is baked in.
• insights returns raw memory context and signal counts for the caller (LLM) to generate recommendations dynamically. Includes keyword-based signal counts but defers semantic interpretation to the caller.
• milestones returns a raw candidate object for the caller (LLM) to validate and classify. No keyword-based auto-detection.
• record defers emotional interpretation to the caller. The emotion frontmatter field is only populated if the caller provides it in metadata.
• task creates a single async task record; batch-task creates multiple tasks in one call.
• delete removes an entry by entry_id, creates a .bak before modification, and updates the total count in meta. Requires --force flag for destructive operations.
• archive copies all memory files and journal_meta.json to a timestamped archive/ directory. Use --clear to reset the journal after archiving. Requires --force flag when using --clear.
• update-meta updates journal metadata (language, goals, preferences). Retroactive translation rules are kept minimal because templates are now English-only by design.
• All data is stored locally under ~/.openclaw/customers/{customer_id}/.
• No external network calls are made.