{"slug": "a-3-layer-memory-system-that-gives-claude-code-persistent-context-across", "title": "A 3-layer memory system that gives Claude Code persistent context across sessions.", "summary": "A developer built ObsiForge, a three-layer memory system that gives Claude Code persistent context across sessions, replacing a manual 45-minute setup with a single command that completes in 30 seconds. The system uses a MEMORY.md file with pointers and rules, a vault of self-contained project notes, and automated observation capture via hooks, with all data stored locally in SQLite and Chroma. The developer also fixed a bug in the Smart Connections MCP server where the `search_notes` function was performing regex matching instead of actual semantic search, and contributed the fix as a pull request to the original repository.", "body_md": "Claude Code forgets everything between sessions. You explain your project, your architecture, your preferences and next session it's ground zero again.\n\nI spent 45 minutes setting this up manually. Debugging ports, copying tokens, configuring MCP servers by hand. Then days debugging the Smart Connections integration.\n\nSo I built ObsiForge, one command that does all of it:\n\n```\nobsiforge init --name myproject --path ~/vaults/myproject\n```\n\n30 seconds + 2 plugin clicks. The rest of this article explains what it configures and why each layer matters.\n\nThree layers, each with a distinct job. No duplication. No redundancy.\n\nEach project gets a MEMORY.md that points to where knowledge lives. It never stores knowledge itself, just pointers and rules.\n\nThis is the only file Claude reads on every session start. ~800 tokens to know where everything is.\n\nThe rules are simple:\n\nThe search tools are listed here:\n\n`mcp__smart-connections__search_notes`\n\n`mcp__obsidian-mcp-tools__get_vault_file`\n\n`mcp__plugin_claude-mem_mcp-search__search`\n\nEach project has a vault with self-contained notes. No wikilinks, no \"see also\", each note has full context.\n\n`project.md`\n\n— architecture, stack, decisions, roadmap`user.md`\n\n— preferences, code style, what works/doesn't`MEMORY.md`\n\n— search tools, session lifecycle, vault index`[other].md`\n\n— assessments, gap analyses, ADRsSmart Connections indexes these at block level (384-dim embeddings via bge-micro-v2, running locally inside Obsidian). The MCP server exposes `search_notes`\n\nto Claude Code.\n\nAutomated capture via hooks. Every tool use gets logged as an observation. At session start, the last 50 observations get injected into context. At session end, `/consolidate`\n\ndistills what matters into the vault.\n\nSQLite + Chroma (vector DB) running locally. Zero cloud dependencies.\n\n**START → /dashboard**\n\n**WORK → normal Claude Code session**\n\n**END → /consolidate**\n\nThe Smart Connections plugin for Obsidian generates embeddings fine, bge-micro-v2, 384 dimensions, block-level indexing. The problem was the MCP server that bridges Claude Code to those embeddings.\n\nIts `search_notes`\n\nfunction was doing regex matching. The code literally said:\n\n\"For now, we'll do a simple keyword match since we don't have a way to generate embeddings for arbitrary text without the model.\"\n\nEvery time Claude Code \"searched semantically,\" it was grepping. A query like \"how to handle offline data sync\" would only find notes containing those exact words, not notes about \"event sourcing\" or \"conflict resolution\" which is the entire point of embeddings.\n\nThe other search tools (`get_similar_notes`\n\n, `get_embedding_neighbors`\n\n) do real semantic search, but they require a pre-existing note path or a raw 384-dim vector. `search_notes`\n\nis the only tool that accepts free text, and it's the one MCP clients call most often.\n\nI added `@xenova/transformers`\n\nto the MCP server and rewrote `searchByQuery`\n\nto generate embeddings from the query text, then find nearest neighbors by cosine similarity.\n\n**Before (regex):** 0 results — no note contains those exact words.\n\n**After (embeddings):** 5 results — similarity 0.60-0.63, conceptually relevant.\n\nI used Claude Code itself to diagnose the bug and write the fix. This is now PR #7 on the original repo.\n\nThis is the kind of thing ObsiForge's `doctor`\n\ncommand catches, if your semantic search isn't actually semantic, you want to know before you rely on it.\n\nMeasured from an active project with 21 vault notes totaling 243KB:\n\n| Layer | What | Token cost |\n|---|---|---|\n| Layer 3 | MEMORY.md (pointers) | ~800 tokens, loaded every session start |\n| Layer 2 | 3 core vault notes | ~5,300 tokens on `/dashboard` call |\n| Layer 1 | claude-mem (50 observations) | ~5,000-15,000 tokens auto-injected at start |\n| Layer 2 | Smart Connections query | ~300-800 tokens on demand per search |\n| Layer 2 | Additional vault note | ~1,000-4,500 tokens on demand per read |\n\nWithout memory (baseline): re-explaining project context costs ~3,000-6,000 tokens per session. And Claude still doesn't have the full picture.\n\nWith memory: ~6,100-20,000 tokens for full context. But you get:\n\nWithout memory, to get the same context you'd need to manually re-explain:\n\n| What you'd re-explain | Token cost |\n|---|---|\n| Project architecture | ~4,200 tokens |\n| User preferences | ~640 tokens |\n| Past decisions and why | ~2,700-10,000 tokens |\n| What was tried and what failed | ~5,000-15,000 tokens |\nTotal without memory |\n10,000-30,000 tokens per session |\n\nAnd the real problem isn't the cost, it's that you wouldn't remember what to include. The session from 3 weeks ago where approach X didn't work? You wouldn't think to mention it. The architectural decision from last month? You'd summarize it differently each time.\n\n**Real token savings: 1.5-2x less per session.** But what's priceless is that claude-mem captures \"we tried X and it failed because Y\" knowledge you wouldn't re-explain because you simply wouldn't remember it.\n\nThe key insight: we never load all 60,700 tokens of the vault. The pointer file (800 tokens) tells Claude where things are, and it pulls knowledge on demand via semantic search. Most sessions need 2-3 vault reads and 1-2 searches.\n\n| Session type | Searches | Reads | Tokens used |\n|---|---|---|---|\n| Quick (1 search, 1 read) | 1 | 1 | ~7,100 |\n| Deep (3 searches, 5 reads) | 3 | 5 | ~18,000 |\n| Continuation (dashboard only) | 0 | 3 | ~6,100 |\n\nclaude-mem's context injection (~5,000-15,000 tokens for 50 observations) is the main cost. But \"we already tried X and it failed because Y\" saves far more tokens than it costs.\n\nConsolidation is a skill, not a script.\n\nThe `/consolidate`\n\nskill requires Claude's judgment: what knowledge belongs in the vault (permanent) vs. what stays in claude-mem (session-level). A script can't decide if \"we switched from REST to gRPC\" is a vault-worthy architectural decision or a temporary debugging note.\n\nWhat I did automate: at session end, a Stop hook runs that checks whether you're in a project with an Obsidian vault and reminds you to consolidate. The actual distillation still needs Claude's judgment, but you no longer have to remember to run `/consolidate`\n\n, the system reminds you.\n\nCross-project boundaries are solved by separate sessions. Each project gets its own vault, its own MEMORY.md, and its own `.mcp.json`\n\n. When you work on project A, Claude loads project A's context. When you switch to project B, you open a new Claude Code session in project B's directory. No cross-contamination. claude-mem is global (it sees all sessions), but `/consolidate`\n\nfilters by project, so observations go to the right vault.\n\nRe-indexing happens inside Obsidian. If you add notes outside Obsidian, re-open Obsidian to trigger re-embedding. The Smart Connections plugin handles this automatically when it's running.\n\nThe 3-layer architecture is a pattern, not a product. You can set it up manually, the steps above work. But the setup is fragile: wrong port, expired token, plugin version mismatch, and nothing works.\n\nObsiForge handles:\n\n`/dashboard`\n\nand `/consolidate`\n\nskills`obsiforge doctor`\n\n— 9 health checks to diagnose any setup issue\n\n```\nuv tool install https://github.com/ssanvi-builds/ObsiForge\nobsiforge init --name myproject --path ~/vaults/myproject\n```\n\nEnable 2 community plugins in Obsidian Settings (security requirement, not bypassable). Done.\n\nIf you want to set it up manually, the steps in the original guide still work, but you'll probably spend some time instead of 30 seconds.\n\ngithub.com/ssanvi-builds/ObsiForge\n\n`search_notes`\n\ntool was regex for months. If your \"semantic search\" only finds exact keyword matches, it's not semantic.`/dashboard`\n\n→ work → `/consolidate`\n\nis the loop. Without it, knowledge rots.The smart-connections-mcp fix is [PR #7](https://github.com/sterling315er/smart-connections-mcp/pull/7) on an MIT-licensed project.\n\nObsiForge is open source and free: [github.com/ssanvi-builds/ObsiForge](https://github.com/ssanvi-builds/ObsiForge)\n\nThe 3-layer architecture is just a pattern, no special code needed, just discipline about what goes where.\n\nIf you're building something similar, the key question isn't \"what tool do I use?\" but \"what does each layer store, and who reads it?\" Get that right, and the tools are interchangeable.", "url": "https://wpnews.pro/news/a-3-layer-memory-system-that-gives-claude-code-persistent-context-across", "canonical_source": "https://dev.to/ssanvi_builds/a-3-layer-memory-system-that-gives-claude-code-persistent-context-across-sessions-1pab", "published_at": "2026-05-25 17:04:39+00:00", "updated_at": "2026-05-25 17:33:44.516667+00:00", "lang": "en", "topics": ["ai-tools", "ai-products", "ai-agents", "large-language-models", "artificial-intelligence"], "entities": ["Claude Code", "ObsiForge", "Smart Connections", "Obsidian", "MCP"], "alternates": {"html": "https://wpnews.pro/news/a-3-layer-memory-system-that-gives-claude-code-persistent-context-across", "markdown": "https://wpnews.pro/news/a-3-layer-memory-system-that-gives-claude-code-persistent-context-across.md", "text": "https://wpnews.pro/news/a-3-layer-memory-system-that-gives-claude-code-persistent-context-across.txt", "jsonld": "https://wpnews.pro/news/a-3-layer-memory-system-that-gives-claude-code-persistent-context-across.jsonld"}}