How the brain works
Raw conversations are source code, the model is the compiler, and the compiled wiki is your queryable second brain.
Your agent's long-term memory follows Andrej Karpathy's LLM Wiki pattern: raw input goes in one side, and a compile step turns it into articles the next session loads.
Three stages, loosely coupled
| Stage | Starts | Reads | Writes |
|---|---|---|---|
| Capture | On its own, when a session ends or the host compacts | The host's transcript | knowledge/raw/sessions/YYYY-MM-DD.md |
| Capture by hand | When you ask | A thought, a note, a file, a URL, a correction | knowledge/raw/inbox/ or knowledge/raw/user/feedback.md |
| Compile | When you run knowledge-compile, or sync, which compiles first | Changed session logs, inbox items, new feedback | knowledge/user/, knowledge/concepts/, knowledge/memory/ |
| Review | When you run self-review | Accumulated feedback and stale memory | Proposed edits you approve. See Self-evolution |
Most people never call compile directly, because sync does.
Capture is automatic
A hook runs the CLI's session-capture every time you exit a session or the host compacts mid-session. It appends the transcript to today's log, with secrets scrubbed first. What is scrubbed: Redaction.
Each host's transcript format has a small adapter inside the capture module. Adding a host is a new adapter, not a new hook script.
Capture anything else by hand
Ask in conversation ("capture this for the inbox", "save as feedback"), or use the CLI. Both end in the same place and feed the same compile. The examples, the flags and the two capture kinds are on the Capture page.
Compile is on demand
knowledge-compile picks up every session log whose hash changed since the last compile, every inbox item, and every new feedback entry. For each one:
- The MCP server returns a synthesis prompt.
- Your session does the synthesis.
- The server confirms the write.
A compile can be interrupted and run again: it tracks hashes, so it never compiles the same input twice.
| Output | Lifecycle | What lives there |
|---|---|---|
knowledge/user/ | Permanent, evolves with you | Profile, skills (including your default technical choices), preferences (your own tastes), career, interests. A working rule you state goes to feedback instead, and graduates into the manual |
knowledge/concepts/ | Permanent, cross-cutting | Patterns spanning several projects; specs distill here |
knowledge/memory/ | Hot context, loads every session | Active threads, recent decisions, learnings from feedback. Daily entries prune after 14 days |
Why this stays cheap
The compile tool returns a prompt. Your session runs the synthesis on your host's plan. The result is written back through another tool call. No LLM-as-a-service inside the plugin, no API billing.