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.

The architecture

Three layers, each with a distinct job. No duplication. No redundancy.

• Layer 3: MEMORY.md (pointers only) → "Where to find things"
• Layer 2: Obsidian vault (knowledge) → "What we know"
• Layer 1: claude-mem (observations) → "What happened this session"

Layer 3 - MEMORY.md (pointers, not content)

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:

• NEVER store actual knowledge here, only pointers.
• Project context goes to the Obsidian vault (Layer 2).
• Session observations go to claude-mem (Layer 1).
• This file is a pointer only.

The search tools are listed here:

• Semantic search: mcp__smart-connections__search_notes
• Specific file: mcp__obsidian-mcp-tools__get_vault_file
• Session history: mcp__plugin_claude-mem_mcp-search__search

Layer 2 — Obsidian vault (project knowledge)

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, ADRs

Smart 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.

Layer 1 — claude-mem (session observations)

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.

The session lifecycle

START → /dashboard

• Read 3 core notes (project.md, user.md, MEMORY.md)
• Check claude-mem for recent activity
• Smart Connections semantic search for related context
• Brief the user

WORK → normal Claude Code session

• claude-mem captures observations automatically
• Smart Connections available for semantic lookups
• Vault notes readable/writable via MCP

END → /consolidate

• Search claude-mem for session observations
• Filter: what belongs in vault vs. what stays in claude-mem
• Update vault notes
• Report what was consolidated

The Smart Connections problem

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.

The fix

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.

Token economics (real data)

Measured from an active project with 21 vault notes totaling 243KB:

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:

• Architecture decisions that would take 10+ minutes to explain.
• Bug fixes from 3 weeks ago that Claude remembers.
• User preferences without re-stating them.

Without memory, to get the same context you'd need to manually re-explain:

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.

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.

What's not automatic (and what I did about it)

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.

ObsiForge automates all of this

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:

• Plugin download and configuration
• MCP server setup with port collision prevention
• Token generation and configuration
• MEMORY.md template with search tools
• /dashboard and /consolidate skills
• Multi-vault support (separate ports, separate configs)
• 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

Takeaways

1. Verify your semantic search is actually semantic. The search_notes tool was regex for months. If your "semantic search" only finds exact keyword matches, it's not semantic.
2. Pointers over copies. MEMORY.md stores ~800 tokens that point to 60,700 tokens of knowledge.
3. Self-contained notes beat wikilinks. Each vault note has full context. No "see X for details" that breaks when X moves.
4. The lifecycle matters more than the storage. /dashboard → work → /consolidate is the loop. Without it, knowledge rots.
5. Consolidation needs judgment. Automate the reminder, not the action. A script can't decide if "we switched frameworks" is vault-worthy or just a session note.
6. Separate projects, separate sessions. One vault per project, one Claude Code session per project. No cross-contamination.
7. Open source tools can have quiet gaps. The MCP server's most-called tool was its least-tested for semantic correctness. Test your tools' claims.
8. Manual setup takes 45+ minutes and breaks easily. Automated setup takes 30 seconds. Use the tool.

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.