Agent memory
Memory your coding agents share, as Markdown notes in your own folder. You can review every note they write.
Memory gives coding agents a place to look before they start and a place to write what they learned. It is not a database: it is a knowledge base you mark as memory, so every recollection and every note an agent writes is an ordinary Markdown file you can open, diff and delete.
How to use it
- Open Settings → Knowledge → Agent memory. The page is a two-step checklist: mark a base as memory, then install the session-start hook for Claude Code, Codex or both.
- Mark the base: pick a knowledge base and switch on agent memory. You can do the same by right-clicking a base in the sidebar.
- Optional: switch on Review agent writes first, so a new note an agent writes lands in
Proposed/inside the base instead of at its root. Nothing moves it out for you: the note is indexed at once and comes back from search marked as proposed. - For the hook, the page has a row per agent. For Claude Code, paste the snippet into
hooksin~/.claude/settings.json. For Codex, paste it at the end of~/.codex/config.toml, then trust it once with/hooksin Codex. PrivateGoat does not write either file; it puts the snippet on the clipboard and ticks the row once it sees the hook (for Codex, inconfig.tomlorhooks.json). - Choose the embedding model: Automatic, Off — word matching only, or a named model (Download embeddinggemma is about 600 MB). Check Ollama again refreshes the status.
An agent can then recall the note relevant to a task — by words, related terms and meaning — and record
what it learned as a new note. Memory is available through memory_recall, memory_search, memory_read,
memory_write, memory_update, memory_forget and memory_feedback (see
MCP tools reference).
Settings
| Setting | Where | Default |
|---|---|---|
| Agent memory base | Settings → Knowledge → Agent memory, or the sidebar right-click | None marked |
| Review agent writes first | Same page, per base | Optional |
| Embedding model | Same page | Automatic, Off, or a named model |
| Session-start hook, Claude Code and Codex | Same page, one row each | Not installed until you paste the snippet |
Memory has its own rule about models: cloud models are never used for memory.
What is stored
| Item | Where |
|---|---|
| Memory notes | Ordinary Markdown files in the marked knowledge base |
| Notes an agent wrote while review was on | Proposed/ inside that base — read and written like any other note |
| Forgotten notes | Archive/ inside that base |
| Recall feedback | ~/Library/Application Support/Sonavia/MemoryFeedback.json |
| Embedding cache | ~/Library/Application Support/Sonavia/MemoryEmbeddings/ |
There is no separate memory database.
What leaves your Mac
Nothing. Embeddings and recall run in Ollama on 127.0.0.1; the embedding model download goes to Ollama's
registry, and cloud models are excluded by a fail-closed rule.
When it is off or fails
- No base marked: the checklist says the step is not done and agents have nothing to recall.
- Embeddings off, or no model: memory still works by word matching, and the page says so.
- The hook is not installed: the agent can still use the MCP tools, but it does not get the session-start preflight.
- Forgetting a note: it moves to
Archive/; it is not deleted. - An agent writes a note while review is on: it is written into
Proposed/and is recalled from there straight away. A note counts as proposed while its first folder isProposed/, so rename it inside that folder and it stays proposed; move it out ofProposed/to lift it out. The app offers no accept button.
Related
- Knowledge bases — the folders memory lives in.
- The local MCP server — the pipe the memory tools use.
- Local models — the embeddings, and the cloud rule.