Content
# 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](https://github.com/VitalikPro13/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:
| Layer | Lives in | Recalled |
|---|---|---|
| Always-relevant rules | CLAUDE.md / agent instructions | every prompt (budgeted) |
| Subsystem reference | the wiki | on demand, by meaning |
| Session learnings | memory files | on demand, by meaning |
| Design intent | your existing docs | on demand, by meaning |
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."
## 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+):
```bash
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.
```json
{
"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:
```json
{
"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
