I built an AI-friendly knowledge base so coding agents stop forgetting project context

frog404 — Thu, 02 Jul 2026 13:49:58 +0000

I have 20+ personal projects. Every time I start a new AI session, I have to re-explain the project structure, what was decided last time, and what to do next. Switching between Claude Code, Codex, and other tools makes it worse — the context doesn't follow.

I built ContextMixer to fix this: a knowledge base where AI agents search, read, and update project documents through MCP or REST API, and humans review them in a web UI.

Why not Notion / Obsidian / local Markdown?

Local Markdown + Git worked for CLI agents but couldn't be accessed from chat-based tools like Claude.ai.

Notion had MCP support, but fetching pages was slow and token-heavy. Its rich block structure is great for humans but inefficient for AI access.

Obsidian is local-first, which rules out chat-based access.

I needed something accessible from both chat and CLI, lightweight for AI, and editable by humans. Nothing fit, so I built my own. It runs on Cloudflare Workers + D1 + R2, entirely within the free tier.

Progressive retrieval

The core design idea: agents choose how much to read.

View	Returns	Tokens
`meta`	title + summary	tens
`outline`	heading structure	hundreds
`section`	one specific section	hundreds–thousands
`full`	entire document	all

A typical flow for "check the auth design":

1. list_docs(collection_id)        → document list with metadata
2. get_doc(doc_id, view="outline") → heading structure
3. get_doc(doc_id, view="section", section="Auth") → just what's needed

Three API calls, but hundreds of tokens instead of thousands. Most queries resolve at meta → section without ever reading the full document.

AI Cortex: structuring project memory

ContextMixer is a generic container. The structure is up to you.

I keep four documents per project:

context — current phase, recent work, unresolved issues, handoff notes for the next session
spec — confirmed goals, requirements, tech stack (nothing tentative)
decisions — design choices with reasoning, including rejected alternatives
notes — library pitfalls, bug workarounds, implementation tips

I call this pattern AI Cortex. The agent reads context at session start and updates it at the end. The next session picks up where the last one left off.

The biggest win: I no longer re-explain previous sessions. The agent reads context and resumes. decisions also helps — "why did we drop Vue?" is answered by the document, not by me repeating myself.

But letting AI write to a knowledge base has risks. Without rules, agents write tentative ideas into spec, create unconfirmed decisions, or duplicate documents. Writing permissions aren't enough — you need writing rules. In my setup, CLAUDE.md specifies things like "don't write to decisions without user confirmation" and "search before creating new documents." Still a work in progress.

Karpathy's LLM Wiki

After I started building ContextMixer, I came across Karpathy's LLM Wiki pattern — where an LLM builds and maintains a structured wiki from raw sources instead of doing RAG lookups every time.

It resonated, but the use cases differ. LLM Wiki is a research library: accumulate and organize what you've read. ContextMixer is a project whiteboard: manage ongoing work across sessions, tools, and access points.

Links

📦 GitHub
🔗 Demo
📄 Project page (detailed design notes)
📝 Japanese article on Zenn