unhollow

Your coding agent starts every session with a hollow memory. Unhollow it.

Unhollow is a tiny local MCP server that provides semantic search over three layers of project knowledge:

1. Memories: session-learned facts your agent writes down as it works (hard-won fixes, decision rationale, user feedback, subtle bug causes)

2. An AI-optimized wiki: dense, retrieval-shaped documentation of every subsystem, generated by the agent itself

3. Living docs: your architecture plan, design docs, CLAUDE.md, whatever long-form markdown you already maintain

The agent queries all of it by meaning, not filename: memory_search("why is AGC disabled on the mic path") returns the right chunk even if no file mentions "AGC" in its name. Everything runs locally: a 45 MB ONNX embedding model on CPU and a SQLite database. Zero API calls, zero cost, nothing leaves your machine.

The name is an inheritance: this system was extracted from Hollow, a distributed E2EE chat app, where it grew organically over months of agent-driven development. What un-hollows an agent's memory deserved to carry the mark.

Why

Coding agents start every session amnesiac. Project instruction files (CLAUDE.md, AGENTS.md) help, but they have a hard size budget: they are loaded into every prompt, so they can only hold the always-relevant rules. Everything else, the deep subsystem knowledge, the "we tried that and it broke" history, the coupling that silently breaks when violated, either gets rediscovered expensively every session or gets lost.

Unhollow splits knowledge by how it should be recalled:

This setup has been battle-tested on Hollow (Flutter + Rust, desktop/mobile, ~50 wiki files, hundreds of memories). It is the difference between an agent that re-derives the architecture every morning and one that says "that's covered in couplings_gotchas.md, and there's a memory saying we already tried that."

Related MCP server: punt-quarry

How it works

memories/*.md ─┐
wiki/*.md ─────┼─> chunker ─> local ONNX embeddings ─> sqlite-vec
docs (plans,   ┘   (split by      (all-MiniLM-L6-v2,      (vector search,
 CLAUDE.md...)      ## headings)    384-dim, CPU)           incremental upsert)

• Chunking: wiki files and docs split at ## headings; each section is one retrieval unit. Memory files are one chunk each, with their frontmatter name and description prepended for better embedding quality.

• Incremental reindex: chunks are content-hashed; memory_reindex() only re-embeds what changed, so it runs in seconds.

• Three MCP tools: memory_search(query, limit), memory_reindex(force), memory_stats().

Quickstart

1. Copy this repo into your project (e.g. tools/unhollow/) or clone it standalone.

2. Install dependencies (Python 3.10+):

   pip install -r requirements.txt

3. Configure: copy unhollow.config.example.json to unhollow.config.json and set your paths. Relative paths resolve against the config file. All keys are optional; sources that don't exist are skipped.

   {
     "memory_dirs": ["~/.claude/projects/YOUR-PROJECT-SLUG/memory"],
     "wiki_dir": "wiki",
     "docs": ["../../CLAUDE.md", "../../docs/ARCHITECTURE.md"]
   }

4. Register the MCP server in your project's .mcp.json (Claude Code) or your agent's MCP config:

   {
     "mcpServers": {
       "unhollow": {
         "command": "python",
         "args": ["-u", "tools/unhollow/server.py"],
         "env": { "PYTHONUNBUFFERED": "1" }
       }
     }
   }

   On first run the server downloads the embedding model (~45 MB, one time) into models/.

5. Generate the wiki: paste prompts/generate-wiki.md into your agent at the repo root. This is the highest-leverage step; the prompt encodes everything we learned about making documentation that retrieves well.

6. Build the index: ask your agent to run memory_reindex().

7. Make the agent actually use it (do not skip this): paste the block from prompts/agent-instructions-snippet.md into whatever your AI always reads — CLAUDE.md, AGENTS.md, Cursor rules, a custom system prompt. It teaches the agent to search before designing, arguing, or re-investigating, and to reindex after writing. Without it the server sits unused.

What's in this repo

server.py, chunker.py, embedder.py, store.py, config.py   # the MCP server (~400 lines total)
unhollow.config.example.json                              # config template
wiki/                                                     # your generated wiki goes here
prompts/generate-wiki.md                                  # the wiki-generation prompt (start here)
prompts/agent-instructions-snippet.md                     # paste-into-CLAUDE.md block that makes the agent USE the tool
prompts/memory-conventions.md                             # memory file format + index discipline
skills/compush/SKILL.md                                   # session wrap-up skill (see below)

The workflow that keeps it alive

Stale documentation is worse than none. The included compush skill (skills/compush/) is an end-of-session routine for Claude Code: copy it to ~/.claude/skills/compush/ or .claude/skills/compush/ and say /compush when wrapping up. It walks the agent through:

1. Save/update memories (search first, update instead of duplicating)

2. Update wiki files the session's changes touched

3. Touch agent instructions only if a durable rule changed (hard budget enforced)

4. Reconcile living docs against what the session touched, nothing more

5. Commit and push (files staged by name)

6. Reindex

Each step is scoped to the current session, so it stays fast and never turns into an audit.

FAQ

Does it need a GPU or API key? No. Embeddings run on CPU via onnxruntime; a full reindex of a ~2 MB corpus takes well under a minute, incremental reindexes take seconds.

Is my code sent anywhere? No. The only network access is a one-time model download from HuggingFace. Search and indexing are fully local.

Can I use a different embedding model? Yes: set hf_model_id, embedding_dim, and max_tokens in the config. The default (all-MiniLM-L6-v2) is a good speed/quality tradeoff for chunk-sized text.

What if I don't use Claude Code? The server is plain MCP over stdio; any MCP-capable agent can use it. The memory directory format is just markdown with frontmatter, usable from any agent that can write files.

Why not just grep? Grep finds words; this finds meaning. "Why do messages arrive out of order" retrieves the Lamport-clock section even though it shares no words with it. Use both.

License

MIT