A 3-layer memory system that gives Claude Code persistent context across sessions.

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.

Claude Code forgets everything between sessions. You explain your project, your architecture, your preferences and next session it's ground zero again. I spent 45 minutes setting this up manually. Debugging ports, copying tokens, configuring MCP servers by hand. Then days debugging the Smart Connections integration. So I built ObsiForge, one command that does all of it: obsiforge init --name myproject --path ~/vaults/myproject 30 seconds + 2 plugin clicks. The rest of this article explains what it configures and why each layer matters. Three layers, each with a distinct job. No duplication. No redundancy. Each project gets a MEMORY.md that points to where knowledge lives. It never stores knowledge itself, just pointers and rules. This is the only file Claude reads on every session start. ~800 tokens to know where everything is. The rules are simple: The search tools are listed here: mcp smart-connections search notes mcp obsidian-mcp-tools get vault file mcp plugin claude-mem mcp-search search Each project has a vault with self-contained notes. No wikilinks, no "see also", each note has full context. project.md — architecture, stack, decisions, roadmap user.md — preferences, code style, what works/doesn't MEMORY.md — search tools, session lifecycle, vault index other .md — 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 to Claude Code. Automated 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 distills what matters into the vault. SQLite + Chroma vector DB running locally. Zero cloud dependencies. START → /dashboard WORK → normal Claude Code session END → /consolidate The 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. Its search notes function was doing regex matching. The code literally said: "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." Every 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. The other search tools get similar notes , get embedding neighbors do real semantic search, but they require a pre-existing note path or a raw 384-dim vector. search notes is the only tool that accepts free text, and it's the one MCP clients call most often. I added @xenova/transformers to the MCP server and rewrote searchByQuery to generate embeddings from the query text, then find nearest neighbors by cosine similarity. Before regex : 0 results — no note contains those exact words. After embeddings : 5 results — similarity 0.60-0.63, conceptually relevant. I used Claude Code itself to diagnose the bug and write the fix. This is now PR 7 on the original repo. This is the kind of thing ObsiForge's doctor command catches, if your semantic search isn't actually semantic, you want to know before you rely on it. Measured from an active project with 21 vault notes totaling 243KB: | Layer | What | Token cost | |---|---|---| | Layer 3 | MEMORY.md pointers | ~800 tokens, loaded every session start | | Layer 2 | 3 core vault notes | ~5,300 tokens on /dashboard call | | Layer 1 | claude-mem 50 observations | ~5,000-15,000 tokens auto-injected at start | | Layer 2 | Smart Connections query | ~300-800 tokens on demand per search | | Layer 2 | Additional vault note | ~1,000-4,500 tokens on demand per read | Without memory baseline : re-explaining project context costs ~3,000-6,000 tokens per session. And Claude still doesn't have the full picture. With memory: ~6,100-20,000 tokens for full context. But you get: Without memory, to get the same context you'd need to manually re-explain: | What you'd re-explain | Token cost | |---|---| | Project architecture | ~4,200 tokens | | User preferences | ~640 tokens | | Past decisions and why | ~2,700-10,000 tokens | | What was tried and what failed | ~5,000-15,000 tokens | Total without memory | 10,000-30,000 tokens per session | And 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. 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. The 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. | Session type | Searches | Reads | Tokens used | |---|---|---|---| | Quick 1 search, 1 read | 1 | 1 | ~7,100 | | Deep 3 searches, 5 reads | 3 | 5 | ~18,000 | | Continuation dashboard only | 0 | 3 | ~6,100 | claude-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. Consolidation is a skill, not a script. The /consolidate skill 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. What 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 , the system reminds you. Cross-project boundaries are solved by separate sessions. Each project gets its own vault, its own MEMORY.md, and its own .mcp.json . 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 filters by project, so observations go to the right vault. Re-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. The 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. ObsiForge handles: /dashboard and /consolidate skills obsiforge doctor — 9 health checks to diagnose any setup issue uv tool install https://github.com/ssanvi-builds/ObsiForge obsiforge init --name myproject --path ~/vaults/myproject Enable 2 community plugins in Obsidian Settings security requirement, not bypassable . Done. If 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. github.com/ssanvi-builds/ObsiForge search notes tool was regex for months. If your "semantic search" only finds exact keyword matches, it's not semantic. /dashboard → work → /consolidate is 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. ObsiForge is open source and free: github.com/ssanvi-builds/ObsiForge https://github.com/ssanvi-builds/ObsiForge The 3-layer architecture is just a pattern, no special code needed, just discipline about what goes where. If 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.