| name | memo |
| description | Use when starting any task (silently recall relevant memories) or when user says "remember this", "save this to memo", "what do I know about", "search memories", "have I seen this before", "recall", "store this", "forget", or asks to edit/list memories. Cross-project memory layer with local semantic search via MCP tools. |
memo
Cross-project persistent memory with local semantic search. All data on-machine at ~/.memo/. Access via MCP tools.
Phase 1: Recall (silent, at task start)
At the start of a technical task, derive a search query from the user's request and call memo_recall without narrating it.
- Skip recall entirely for conversational or meta turns ("hi", "/clear", "what did we just do", status questions).
- Surface only results with
score >= 0.70. If nothing clears that bar, say nothing about memo at all.
- Never announce "searching memories" — weave relevant results into the response naturally, or stay silent.
Query derivation examples:
| User says | Query |
|---|
| "Fix the CORS error in our API" | "CORS error API fix" |
| "Set up MongoDB connection pooling" | "MongoDB connection pooling configuration" |
| "Debug flaky test in CI" | "flaky test CI debugging" |
Phase 2: Ask before saving (rare, at task end)
Do not save anything without explicit user consent. Do not pre-compose or pitch a memory.
If and only if a task produced a non-obvious, cross-project insight, ask once with this exact short prompt:
Do you want to save this to memo?
That's the entire prompt. No preamble, no summary of what would be saved, no "this seems worth remembering". The user decides.
Ask only when all of these hold:
- The insight is non-obvious (the root cause or resolution wasn't immediately apparent).
- It would help in a different project too, not just this repo.
- The user hasn't already declined saving earlier in the session.
Stay silent when:
- The fix was routine (typo, rename, obvious bug).
- The insight is project-local (build commands, repo layout, team workflow) — that belongs in
MEMORY.md, not memo.
- You are unsure. When in doubt, do not ask. One save prompt per task, maximum.
Saving When Asked
When the user says "save this to memo", "remember this", or answers yes to the Phase 2 prompt, capture everything that would help future-you reconstruct the problem and solution without the original conversation. A terse one-liner is a failure mode here.
Include in the memory body:
- Problem — the exact symptom, including error messages verbatim.
- Root cause — why it happens, not just what fixes it.
- Fix — the specific change, with a fenced code snippet for the key diff or reproducer.
- Why the fix works — the invariant or guarantee the fix relies on.
- Specifics — tool/library names and versions, relevant flags, commands, file paths if cross-project meaningful.
- Gotchas — edge cases or conditions where the fix does not apply.
Populate the context object on memo_remember with any of these that are known:
| Key | What to put there |
|---|
ticket | Jira/issue key mentioned in session (e.g. APP-1234) |
pr | PR URL if one is open or merged for this fix |
project | Explicit project name (overrides git auto-capture when the fix is attributed to a different repo) |
related | Memory ID (full UUID or 8-hex short-id) of a prior memo this extends |
Git auto-capture fills in project from the cwd automatically — explicit values override it on the same key.
Split multi-topic insights into separate memo_remember calls. One topic per memory.
If memo_remember returns "status": "similar_exists", follow the Handling Duplicates flow below.
MCP Tool Map
| Tool | Use when |
|---|
memo_recall | Start of a technical task — silent context gathering |
memo_search | User explicitly asks "what do I know about X" |
memo_similar | Pre-check before storing, to spot an existing near-duplicate |
memo_list | User wants to browse memories by recency |
memo_remember | User confirmed save |
memo_update | Merging new details into an existing memory |
memo_forget | User asks to delete (accepts full UUID or 8-hex short-id) |
memo_reconcile | User edited the Obsidian vault (deleted or moved files) and wants the DB to reflect those structural changes |
memo vs MEMORY.md
memo = cross-project insight (debugging patterns, tool gotchas, tech decisions that recur elsewhere). MEMORY.md = project-local convention (build commands, repo structure, team workflow). If in doubt: "would this help in a DIFFERENT project?" — yes = memo, no = MEMORY.md.
Auto-Tagging
First tag is always the project name (from git remote or directory name). Add 1-3 descriptive tags (technology, domain, pattern).
Example: ["ttsensei", "mongodb", "connection-pooling", "timeout"]
Handling Duplicates
When memo_remember returns "status": "similar_exists":
- Show the existing memory content to the user.
- Ask: "A similar memory already exists. Update it or keep both?"
- If update: use
memo_update with merged content.
- If keep: user explicitly confirms, then re-store with differentiated content.
Content Quality Rules
- Self-contained: enough context that the memory makes sense without the original conversation.
- Problem + Solution: always pair what went wrong with what fixed it.
- Include "why": not just "use X" but "use X because Y fails under Z conditions".
- One topic per memory: split multi-topic insights into separate memories.
- Specific names: exact technology names and versions ("MongoDB 7.0 change streams" not "database streaming").
- No ephemeral details: omit session-specific paths, timestamps, or "I tried X then Y" narrative.
