context-memory

Context Memory Skill

Saves and searches past Claude Code sessions so context, decisions, and code persist across conversations.

Trigger Phrases

Activate this skill when the user says:

• "remember this" / "save this session" / "store this for later"
• "recall" / "search past sessions"
• "what did we discuss about..."
• "find previous work on..."
• "look up past decisions about..."
• "context memory"

Do NOT activate for:

• General file storage or note-taking requests
• Bookmark or URL management
• Requests about Claude's built-in memory features

Database Location

• Database: ~/.claude/context-memory/context.db
• Scripts: ~/.claude/skills/context-memory/scripts/

Commands

/remember [note]

Save the current session with an optional annotation.

/recall <query> [options]

Search past sessions.

• --project: Limit to current project
• --detailed: Include full message content and code snippets
• --limit N: Maximum results (default: 10)

Examples

Example 1: Save after a debugging session

User says: /remember "Fixed the JWT refresh bug" Actions:

1. Analyze conversation, generate structured summary
2. Extract topics: debugging, jwt, authentication
3. Select key messages capturing the problem and fix
4. Write JSON with all fields and save via --json Result: "Session saved. Summary: Fixed JWT refresh token expiration bug by adding clock skew tolerance. Topics: debugging, jwt, authentication. Messages: 8 saved. Snippets: 1 saved. Note: Fixed the JWT refresh bug."

Example 2: Find past work on a topic

User says: "what did we discuss about database migrations?" Actions:

1. Run db_search.py "database migrations" --format markdown
2. Present matching sessions with summaries and topics Result: Sessions displayed with brief summaries. Offer --detailed for full context.

Example 3: Deep dive into a past session

User says: /recall authentication --detailed Actions:

1. Run db_search.py "authentication" --detailed --format markdown
2. Present full summaries, key messages, and code snippets Result: Complete session context with decisions, messages, and code excerpts in expandable sections.

Saving a Session

When the user wants to save/remember the current session:

1. Generate a structured summary:

   • brief: One-line summary of what was accomplished
   • detailed: 2-3 paragraph detailed summary
   • key_decisions: List of important decisions made
   • problems_solved: List of problems that were resolved
   • technologies: List of technologies/tools used
   • outcome: success | partial | abandoned

2. Extract 3-8 relevant topics (lowercase, e.g., "authentication", "react", "debugging")

3. Identify significant code snippets worth preserving

4. Select 5-15 key messages that capture the problem, decisions, and solutions

5. Pipe the JSON via stdin using --json -:

python "~/.claude/skills/context-memory/scripts/db_save.py" --json - << 'ENDJSON'
{
  "session_id": "<UNIQUE_ID>",
  "project_path": "<PROJECT_PATH>",
  "messages": [
    {"role": "user", "content": "..."},
    {"role": "assistant", "content": "..."}
  ],
  "summary": {
    "brief": "One-line summary",
    "detailed": "Full 2-3 paragraph summary...",
    "key_decisions": ["Decision 1", "Decision 2"],
    "problems_solved": ["Problem 1"],
    "technologies": ["python", "sqlite"],
    "outcome": "success"
  },
  "topics": ["topic1", "topic2"],
  "code_snippets": [
    {
      "code": "def example(): pass",
      "language": "python",
      "description": "What this does",
      "file_path": "src/example.py"
    }
  ],
  "user_note": "User's note or null"
}
ENDJSON

Important: Always use --json - (stdin) for /remember saves. This avoids temp file issues on Windows. The CLI args path (--brief, --topics) only saves a subset of fields and leaves --detailed recall empty.

6. Report back: confirmation, brief summary, topics extracted, message/snippet counts, user note included.

Searching Past Sessions

When the user wants to recall/search past sessions:

1. Run the search:

python "~/.claude/skills/context-memory/scripts/db_search.py" "<QUERY>" --format markdown [--project "$(pwd)"] [--detailed] [--limit N]

2. Present results in a clear, scannable format.

3. If results are insufficient, offer to:

   • Broaden the search query
   • Remove the --project filter
   • Search with --detailed for deeper content

Output Format

# Context Memory Results
**Query**: "authentication"
**Results**: 3 sessions

---
## 1. 2026-01-15 | my-app (Match #1)
**Summary**: Implemented JWT auth with refresh token rotation
**Topics**: authentication, JWT, security, Node.js
**Decisions**:
- Use RS256 for token signing
- 15-minute access token expiry

<details><summary>Full Context</summary>
[Detailed content here]
</details>

Error Handling

• Database doesn't exist: Auto-created on first save. To manually init: python ~/.claude/skills/context-memory/scripts/db_init.py
• Database locked: Another process may be using it. Ask the user to check for other Claude Code instances and retry.
• Save fails: Check file permissions on ~/.claude/context-memory/. The directory must be writable.
• Search returns no results: Suggest broader terms, remove --project filter, or try related keywords.
• Empty database (fresh install): Show "No sessions stored yet. Use /remember to save your first session."

Best Practices

1. When saving: Always use --json for full data. Always ask user if they want to add a note/annotation
2. When searching: Start with tier 1 (summary-ranked with topic/snippet boost), offer detailed search if needed
3. Topics: Use consistent, lowercase topic names
4. Summaries: Focus on the "why" not just the "what"
5. Code snippets: Only save truly reusable or significant code

Pre-Compact Context Checkpoints

The plugin saves a full conversation checkpoint before Claude Code compacts context, preventing loss of detail.

How it works

1. PreCompact hook (pre_compact_save.py) — Triggered automatically before compaction. Reads the transcript and saves all messages to the context_checkpoints table without truncation or sampling.
2. context_load_checkpoint MCP tool — Restores the full conversation after compaction. Accepts session_id, project_path, and optional last_n_messages parameters.
3. Checkpoint pruning — db_prune.py prunes old checkpoints (per-session and age-based) alongside regular session pruning.

The context_checkpoints table (schema v4) stores:

• session_id, project_path, project_hash — checkpoint identity
• checkpoint_number, trigger_type — sequencing and trigger source (auto or manual)
• messages — full JSON message array
• message_count, created_at — metadata

Post-compaction recovery

After compaction, call the context_load_checkpoint MCP tool with the current project path to restore full conversation detail. Only use this when the compaction summary is missing information you need.

MCP Tools

The optional MCP server (mcp_server.py) exposes these tools:

• context_search — Search past sessions (FTS5 + BM25 ranking)
• context_save — Save a session with messages, summary, topics, snippets
• context_stats — Database statistics (table counts, DB size)
• context_init — Initialize or verify the database schema
• context_load_checkpoint — Load a pre-compact context checkpoint
• context_dashboard — Launch the web dashboard in the background

Requires Python >= 3.10 and pip install mcp.

Related Files

• Schema Reference — Full database schema (v4)
• Scripts in scripts/ directory