Memory

Long-term memory across sessions — search, read, save. The memory skill gives CLI-JAW persistent recall of user preferences, project decisions, and durable knowledge that survives beyond a single conversation.

Quick Reference

Overview

The memory skill is the persistent knowledge layer for CLI-JAW. It enables the AI to remember facts, preferences, and decisions across sessions without relying solely on conversation context. Every session has the memory skill injected automatically — there is no need to load it manually.

Memory operates at two scopes:

Rules

The memory skill follows seven strict rules that govern when and how memory is used:

Commands

Search

Search the memory index for keywords. Returns matching entries with their source file paths.

# Basic keyword search
cli-jaw memory search "keyword"

# Search for user preferences
cli-jaw memory search "user preference"

# Search with error codes or technical terms
cli-jaw memory search "auth login 401"

# Search with system/service terms
cli-jaw memory search "launchd plist service"

# Cross-instance search (L2 dashboard, read-only)
cli-jaw dashboard memory search "cross-instance topic"

Read

Read the full contents of a specific memory file, or a line range within it.

# Read the user profile
cli-jaw memory read structured/profile.md

# Read a semantic knowledge file
cli-jaw memory read structured/semantic/cli-jaw.md

# Read an episodic entry
cli-jaw memory read structured/episodes/live/2026-03-07.md

# Read only specific lines (useful for large files)
cli-jaw memory read structured/profile.md --lines 1-30

Save

Append durable facts to a memory file. Content is appended, not overwritten.

# Save a user preference to the profile
cli-jaw memory save structured/profile.md "- User prefers Korean UI and English code"

# Save a technical fact to a semantic file
cli-jaw memory save structured/semantic/cli-jaw.md "- Memory runtime uses task snapshots before response generation"

# Save a time-bound episode
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

Utility commands for inspecting and initializing the memory directory.

# List all memory files and their sizes
cli-jaw memory list

# Initialize the memory directory structure (first-time setup)
cli-jaw memory init

Storage Layout

Memory is organized into a structured directory hierarchy under ~/.cli-jaw/memory/. Each subdirectory serves a distinct purpose:

~/.cli-jaw/memory/
  structured/
    profile.md                          # User preferences and identity
    index.sqlite                        # Full-text search index
    episodes/
      live/
        2026-03-07.md                   # Daily episodic entries
        2026-05-29.md
    semantic/
      cli-jaw.md                        # CLI-JAW-specific knowledge
      deployment.md                     # Deployment procedures
      project-architecture.md           # Architecture decisions
    procedures/
      release-checklist.md              # Reusable workflows
      code-review-process.md
    sessions/
      session-2026-05-29-abc123.md      # Auto-extracted session notes

Workflows

The memory skill defines four standard workflows that govern how memory is used during a conversation.

New Conversation

When a new session begins:

User Mentions a Preference

When the user states a preference (e.g., "I prefer tabs over spaces"):

User Asks "Do you remember...?"

When the user asks whether something was previously discussed:

End of Important Session

When a session yields a significant decision or outcome:

Usage Examples (~해줌)

Here are real-world usage patterns in the natural Korean style that CLI-JAW understands.

What to Save vs. What to Skip

Choosing the Right Destination

When saving a fact, select the destination based on the nature of the information:

Search Tips

The memory search index supports full-text keyword matching. To get the best results:

• Use both languages — search "auth" and "인증" if the user works bilingually
• Include error codes — search "401 unauthorized" to find auth-related memories
• Try file names — search "launchd" or "plist" for system service memories
• Be specific then broad — start with "Cloudflare D1 migration" then fall back to "database migration"
• Search symbols — error codes like "ECONNREFUSED" or config keys like "JAW_HOME" are indexed

Notes

• Prefer concise, durable entries over verbose logs
• Memory is append-only by convention — save commands append, they do not overwrite
• The search index (index.sqlite) is automatically maintained when files are saved
• Cross-instance (L2) memory is always read-only; you cannot save to another instance
• If embedding search is enabled in your instance, it supplements but does not replace keyword search

Related

• Concepts: Memory — high-level overview of the memory system architecture
• CLI Commands — full cli-jaw memory command reference
• Dashboard Guide — L2 dashboard memory and cross-instance federation
• Skill Catalog — browse all 118 skills
• Productivity Skills — category page for memory and related skills