Long-term Memory
Rules
- Search before answering about past work, decisions, or preferences. Identify the proper noun, version, error, or file; try short Korean and English keyword variants in L1 memory, then L1 chat.
- Save durable facts immediately — user preferences, key decisions, stable project facts.
- Use structured destinations — prefer
structured/profile.md,structured/semantic/..., orstructured/episodes/.... - Open the source — read the relevant saved file or full chat message with context before stating exact wording or completion. An injected snapshot locates evidence; it does not verify the source.
- Save stable facts only — not transient TODOs, phase logs, or temporary checklists.
- Check chronology — a request or plan is not completed work. Check for later corrections and the applicable date or version.
- Admit checked gaps — only after memory and chat searches and relevant source reads, state what range or source you checked and what remains unverified.
Scope: L1 vs L2
- L1 instance-local memory:
cli-jaw memory search/read/save; default path; current instance only; read/write. - L2 dashboard memory:
cli-jaw dashboard memory search/read/instances; cross-instance federation; read-only. - Use L2 only when the user asks for dashboard memory, all instances, another instance/home, or cross-instance context.
- Save stable facts only through L1
cli-jaw memory save. - Embedding search is optional and default OFF; do not assume it is enabled.
Commands
Search
cli-jaw memory search "keyword"
cli-jaw memory search "user preference"
cli-jaw memory search "auth login 401"
cli-jaw memory search "launchd plist service"
cli-jaw dashboard memory search "cross-instance topic"
Read
cli-jaw memory read structured/profile.md
cli-jaw memory read structured/semantic/cli-jaw.md
cli-jaw memory read structured/episodes/live/2026-03-07.md
cli-jaw memory read structured/profile.md --lines 1-30
Save
cli-jaw memory save structured/profile.md "- User prefers Korean UI and English code"
cli-jaw memory save structured/semantic/cli-jaw.md "- Memory runtime uses task snapshots before response generation"
cli-jaw memory save structured/episodes/live/2026-03-07.md "## 16:30\n- Decided to remove query-provider setup from memory UX"
List & Init
cli-jaw memory list
cli-jaw memory init
Storage Layout
| Path | Purpose |
|---|---|
{{JAW_HOME}}/memory/structured/profile.md |
Stable profile, preferences, long-lived project context |
{{JAW_HOME}}/memory/structured/episodes/ |
Time-ordered episodic memory |
{{JAW_HOME}}/memory/structured/semantic/ |
Durable facts and extracted knowledge |
{{JAW_HOME}}/memory/structured/procedures/ |
Reusable workflows and rules |
{{JAW_HOME}}/memory/structured/sessions/ |
Optional session-derived memory |
{{JAW_HOME}}/memory/structured/index.sqlite |
Search index |
Workflows
New Conversation
- Use injected memory context if present
- Search memory if the task depends on prior decisions or preferences
- Read the relevant file when exact wording or details matter
User Mentions a Preference
- Acknowledge briefly
- Save to
structured/profile.md - If it is project-specific, also save to an appropriate semantic file
User Asks "Do you remember...?"
- Run
cli-jaw memory search "<keywords>" - Read a matching file; check later corrections before citing it
- If memory misses, run
cli-jaw chat search "<keywords>" --all-sessionswith keyword variants and context - If both miss, state the checked gap and offer to save a durable fact
End of Important Session
- Save the durable decision or fact
- Use episodic files for time-bound outcomes
- Use semantic/profile files for long-lived knowledge
Chat Search (L1)
Search past conversation messages in the current instance. Use when you need prior conversation context — what was discussed, decided, or debugged.
cli-jaw chat search "<keywords>"
cli-jaw chat search "<keywords>" --days 3 # limit to recent N days
cli-jaw chat search "<keywords>" --recent 100 # limit to most recent N messages
cli-jaw chat search "<keywords>" --context 2 # show ±N surrounding messages
cli-jaw chat search "<keywords>" --limit 20 # cap matching results
cli-jaw chat search "<keywords>" --all-sessions # search all sessions in this instance
cli-jaw memory search "<keywords>" --chat # memory plus a 7-day chat supplement
Use chat search after a memory miss. --recent counts messages; combine it with --context for focused lookups. Search hits are locators: inspect surrounding messages and later corrections before claiming a decision or completed action.
Context (memory→chat jump)
Find chat messages related to a memory file by its creation time and keywords.
cli-jaw memory context structured/semantic/cli-jaw.md
cli-jaw memory context structured/episodes/live/2026-06-08.md --window 8
cli-jaw memory context feedback_no-idle-waiting.md --window 2 --limit 5
How it works:
- Uses
created_atfrontmatter (or file mtime) as the time center - Extracts keywords from
name:→description:→ filename stem →kind:→ body first line - Splits compound terms into individual words for OR-based LIKE search
- Searches
messagesDB in a ±window hour range (default 4 hours) - Cross-session — not limited to one conversation
L2 Chat Search
Search jaw.db chat messages across all registered instances (read-only).
cli-jaw dashboard chat search "memory architecture"
cli-jaw dashboard chat search "auth" --instance 3457,3458
cli-jaw dashboard chat search "deploy" --days 7 --limit 20
cli-jaw dashboard chat search "error" --json
How it works:
- Opens each instance's
jaw.dbin readonly mode - Schema probe: auto-detects
tool_logcolumn for extended search - Reports warnings for native module mismatch, missing DB, schema issues
- Results sorted by
created_atDESC across all instances
Notes
- Prefer concise, durable entries over verbose logs