Context Memory

1---
2name: "context-memory"
3description: >
4  Saves and searches past Claude Code sessions so context, decisions, and
5  code persist across conversations. Use when user says 'remember this',
6  'save this session', 'recall', 'search past sessions', 'what did we
7  discuss about', or 'find previous work on'. Do NOT use for general file
8  storage, note-taking, or bookmark management.
9license: "MIT"
10compatibility: "Requires Python >= 3.8 with sqlite3 FTS5 support (included in standard library). MCP server requires Python >= 3.10. Claude Code CLI only."
11allowed-tools: "Bash(python:*)"
12metadata:
13  author: "ErebusEnigma"
14  version: "1.3.1"
15---
16 
17# Context Memory Skill
18 
19Saves and searches past Claude Code sessions so context, decisions, and code persist across conversations.
20 
21## Trigger Phrases
22 
23Activate this skill when the user says:
24- "remember this" / "save this session" / "store this for later"
25- "recall" / "search past sessions"
26- "what did we discuss about..."
27- "find previous work on..."
28- "look up past decisions about..."
29- "context memory"
30 
31Do NOT activate for:
32- General file storage or note-taking requests
33- Bookmark or URL management
34- Requests about Claude's built-in memory features
35 
36## Database Location
37 
38- Database: `~/.claude/context-memory/context.db`
39- Scripts: `~/.claude/skills/context-memory/scripts/`
40 
41## Commands
42 
43### /remember [note]
44Save the current session with an optional annotation.
45 
46### /recall \<query\> [options]
47Search past sessions.
48- `--project`: Limit to current project
49- `--detailed`: Include full message content and code snippets
50- `--limit N`: Maximum results (default: 10)
51 
52## Examples
53 
54### Example 1: Save after a debugging session
55User says: `/remember "Fixed the JWT refresh bug"`
56Actions:
571. Analyze conversation, generate structured summary
582. Extract topics: `debugging`, `jwt`, `authentication`
593. Select key messages capturing the problem and fix
604. Write JSON with all fields and save via `--json`
61Result: "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."
62 
63### Example 2: Find past work on a topic
64User says: "what did we discuss about database migrations?"
65Actions:
661. Run `db_search.py "database migrations" --format markdown`
672. Present matching sessions with summaries and topics
68Result: Sessions displayed with brief summaries. Offer `--detailed` for full context.
69 
70### Example 3: Deep dive into a past session
71User says: `/recall authentication --detailed`
72Actions:
731. Run `db_search.py "authentication" --detailed --format markdown`
742. Present full summaries, key messages, and code snippets
75Result: Complete session context with decisions, messages, and code excerpts in expandable sections.
76 
77## Saving a Session
78 
79When the user wants to save/remember the current session:
80 
811. Generate a structured summary:
82   - **brief**: One-line summary of what was accomplished
83   - **detailed**: 2-3 paragraph detailed summary
84   - **key_decisions**: List of important decisions made
85   - **problems_solved**: List of problems that were resolved
86   - **technologies**: List of technologies/tools used
87   - **outcome**: success | partial | abandoned
88 
892. Extract 3-8 relevant topics (lowercase, e.g., "authentication", "react", "debugging")
90 
913. Identify significant code snippets worth preserving
92 
934. Select 5-15 key messages that capture the problem, decisions, and solutions
94 
955. Pipe the JSON via stdin using `--json -`:
96```bash
97python "~/.claude/skills/context-memory/scripts/db_save.py" --json - << 'ENDJSON'
98{
99  "session_id": "<UNIQUE_ID>",
100  "project_path": "<PROJECT_PATH>",
101  "messages": [
102    {"role": "user", "content": "..."},
103    {"role": "assistant", "content": "..."}
104  ],
105  "summary": {
106    "brief": "One-line summary",
107    "detailed": "Full 2-3 paragraph summary...",
108    "key_decisions": ["Decision 1", "Decision 2"],
109    "problems_solved": ["Problem 1"],
110    "technologies": ["python", "sqlite"],
111    "outcome": "success"
112  },
113  "topics": ["topic1", "topic2"],
114  "code_snippets": [
115    {
116      "code": "def example(): pass",
117      "language": "python",
118      "description": "What this does",
119      "file_path": "src/example.py"
120    }
121  ],
122  "user_note": "User's note or null"
123}
124ENDJSON
125```
126 
127**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.
128 
1296. Report back: confirmation, brief summary, topics extracted, message/snippet counts, user note included.
130 
131## Searching Past Sessions
132 
133When the user wants to recall/search past sessions:
134 
1351. Run the search:
136```bash
137python "~/.claude/skills/context-memory/scripts/db_search.py" "<QUERY>" --format markdown [--project "$(pwd)"] [--detailed] [--limit N]
138```
139 
1402. Present results in a clear, scannable format.
141 
1423. If results are insufficient, offer to:
143   - Broaden the search query
144   - Remove the `--project` filter
145   - Search with `--detailed` for deeper content
146 
147## Output Format
148 
149```markdown
150# Context Memory Results
151**Query**: "authentication"
152**Results**: 3 sessions
153 
154---
155## 1. 2026-01-15 | my-app (Match #1)
156**Summary**: Implemented JWT auth with refresh token rotation
157**Topics**: authentication, JWT, security, Node.js
158**Decisions**:
159- Use RS256 for token signing
160- 15-minute access token expiry
161 
162<details><summary>Full Context</summary>
163[Detailed content here]
164</details>
165```
166 
167## Error Handling
168 
169- **Database doesn't exist**: Auto-created on first save. To manually init: `python ~/.claude/skills/context-memory/scripts/db_init.py`
170- **Database locked**: Another process may be using it. Ask the user to check for other Claude Code instances and retry.
171- **Save fails**: Check file permissions on `~/.claude/context-memory/`. The directory must be writable.
172- **Search returns no results**: Suggest broader terms, remove `--project` filter, or try related keywords.
173- **Empty database (fresh install)**: Show "No sessions stored yet. Use /remember to save your first session."
174 
175## Best Practices
176 
1771. **When saving**: Always use `--json` for full data. Always ask user if they want to add a note/annotation
1782. **When searching**: Start with tier 1 (summary-ranked with topic/snippet boost), offer detailed search if needed
1793. **Topics**: Use consistent, lowercase topic names
1804. **Summaries**: Focus on the "why" not just the "what"
1815. **Code snippets**: Only save truly reusable or significant code
182 
183## Pre-Compact Context Checkpoints
184 
185The plugin saves a full conversation checkpoint before Claude Code compacts context, preventing loss of detail.
186 
187### How it works
188 
1891. **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.
1902. **`context_load_checkpoint` MCP tool** — Restores the full conversation after compaction. Accepts `session_id`, `project_path`, and optional `last_n_messages` parameters.
1913. **Checkpoint pruning** — `db_prune.py` prunes old checkpoints (per-session and age-based) alongside regular session pruning.
192 
193The `context_checkpoints` table (schema v4) stores:
194- `session_id`, `project_path`, `project_hash` — checkpoint identity
195- `checkpoint_number`, `trigger_type` — sequencing and trigger source (`auto` or `manual`)
196- `messages` — full JSON message array
197- `message_count`, `created_at` — metadata
198 
199### Post-compaction recovery
200 
201After 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.
202 
203## MCP Tools
204 
205The optional MCP server (`mcp_server.py`) exposes these tools:
206 
207- `context_search` — Search past sessions (FTS5 + BM25 ranking)
208- `context_save` — Save a session with messages, summary, topics, snippets
209- `context_stats` — Database statistics (table counts, DB size)
210- `context_init` — Initialize or verify the database schema
211- `context_load_checkpoint` — Load a pre-compact context checkpoint
212- `context_dashboard` — Launch the web dashboard in the background
213 
214Requires Python >= 3.10 and `pip install mcp`.
215 
216## Related Files
217 
218- [Schema Reference](references/schema-reference.md) — Full database schema (v4)
219- Scripts in `scripts/` directory
220