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, roadmapuser.md
— preferences, code style, what works/doesn'tMEMORY.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
skillsobsiforge 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 on an MIT-licensed project.
ObsiForge is open source and free: 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.