Repository navigation
Releases
v0.3.0 (preview): search by meaning, and recall that asks first
A database engine purpose-built for AI memory. This release adds search by meaning, and recall now shows what it will remove and asks before erasing.
Search by meaning
- Vector indexes in the library. An agent can keep vector indexes and find lots and memories by meaning. The new calls are
CreateIndex,Embed,EmbedBatch,Search,Indexes,VerifyIndexandDropIndex.- No model in the library. You supply the embeddings, and cheesedb never calls a model.
- Exact results. Search uses cosine similarity, and the results are the same as checking every vector.
- Recall reaches the vectors too. A recall removes the vectors of everything it removes, at once, so a recalled memory never comes back in a search.
EraseandCompactremove them from disk. - Indexes are kept apart. Each index has its own folder, log and hash chain. An agent without an index writes exactly the same files and records as before.
- A quarter of the RAM. Vectors are held in memory at one byte per value. The few that could make the top results are re-checked against the exact values on disk, so results don't change. At 1M memories that is 1.1 GB instead of 3.6 GB.
- Measured from 1,000 to 1M memories. With the store open in a Go program, search takes 1.1 ms at 1,000 memories and 142 ms at 1M. The command and the MCP server reload the index on every call: 10 ms at 1,000 and 7.5 s at 1M. Details: BENCHMARKS.md.
Ask in plain English, from the command line and MCP apps
To enable this, set embed_model in llm.conf. embed_base_url and embed_api_key are optional, and any OpenAI-compatible server works. Then:
rememberstores a vector with each memory, and MCP apps get asearchtool.- New commands:
cheesedb searchfinds memories by meaning.cheesedb embedmakes existing memories searchable, or rebuilds the index after a model change.cheesedb indexmanages the indexes.
cheesedb asksearches first. It gives the chat model only the closest live memories (10 by default), so it still works when an agent has thousands.cheesedb forget <agent> "<what>"finds the memory closest to your words and shows it with everything that would go with it. It erases only after you say yes, and if anything changes while you read the list, it shows the new list and asks again.cheesedb learnmakes what it learns searchable, so another app sharing the same memory finds it.cheesedb findnow also searches inside index folders.
Recall asks before it erases
A recall can't be undone, so the MCP recall tool now takes two calls:
- Preview. The first call removes nothing. It lists what would be removed and gives a confirm code that fits only that exact list. If anything changes in between, the model gets a fresh preview.
- Confirm. The second call, with the code, recalls.
Apps that support MCP elicitation also ask you directly, in a form the model can't fill in. Nothing is erased without your tick.
In other apps the two calls are a speed bump, not a lock, so set recall to need your approval in the app's tool permissions.
For Go programs, WouldRecall previews a recall without writing anything.
Safer by default
- Tool answers can't be faked. Memory text that contains line breaks or control characters is quoted in
search,getandlist_memories, so it can't pass for extra lines. - Server replies are size-capped, and error messages show server addresses without user names or passwords.
- Removed vectors don't linger. Removing a vector wipes its bytes from the index.
- Closing an agent no longer holds the store's lock while a write finishes, so other agents can be opened and closed meanwhile.
Compatibility
- Data from v0.2.0 opens unchanged. The main log format is the same. A golden store written by v0.2.0 is kept in the tests: every later version must open it with the same fingerprint and answers.
- Index folders are new. They use a new record type that appears only inside them. The index format may still change while it is a preview.
- MCP:
recallnow answers its first call with a preview instead of recalling.
Try it
go install github.com/govinargo-labs/cheesedb/cmd/cheesedb@v0.3.0
go run github.com/govinargo-labs/cheesedb/examples/vector-search@v0.3.0 # offline demo
Examples:
examples/vector-searchruns offline, or against a real embedding model.examples/plain-englishwalks through the whole story from the command line: search, ask, recall, erase, find and verify.
Website: cheesedb.dev now has a step-by-step recall game, plus pages for MCP, numbers and limits.
Known limits
- Preview. This release has not had an independent security review, and the API and formats may change before v1.0.
- Windows: erasing and cutting a damaged log end don't work yet (issues #27 and #36).
- Large agents over MCP are slow. The MCP server and the command reload the index on every call, which takes seconds at 1M memories.
v0.2.0 (preview): now with an MCP server
A local MCP server. cheesedb mcp lets Claude Code, Cursor and other MCP apps use one agent's memory with no code, through five tools: add_lot, remember, recall, get and list_memories. No tool takes an agent id, recall erases the text from disk by default, and get never shows recalled text.
A model that can run shell commands can still bypass the tools. See the README and THREAT_MODEL.md.
Also: CI now runs staticcheck and govulncheck, and Open no longer fails on Windows because of the directory flush.
Install: go install github.com/govinargo-labs/cheesedb/cmd/cheesedb@latest, then claude mcp add cheesedb -- cheesedb mcp alice.
v0.1.1 (preview)
updated the website url (#35) Signed-off-by: govinargo <156787779+govinargo@users.noreply.github.com>
v0.1.0 (preview)
First public preview of cheesedb: agent memory with a recall button.
Every memory records the sources it was learned from. Recall a bad source, and everything learned from it goes too. cheesedb is an embedded, append-only, hash-chained memory database for AI agents, written in Go with the standard library only.
Preview. cheesedb has not had an independent security review, and the API and on-disk format may change before v1.0. It is not yet recommended for production data. See Limits.
Highlights
- Memory model: sources (lots) and memories with legs.
FairandStrictrecall of a source or a memory, plusGetandActive. - Erasure:
Recall(..., Erase)removes the text from the files on disk before it returns.Compact()erases all dead text. - Storage: an append-only log in numbered segments with seal files. Every write is flushed to disk before it is acknowledged, with torn-tail recovery and a hash chain checked on every open.
Verify()returns the head fingerprint. - Isolation: one store folder of agents, each reachable only with its own token. A file lock keeps a second process out.
- The
cheesedbcommand: every feature from the command line, plus a demo with a real LLM that compares a plain memory list,UntrustedandErase. - Benchmarks against SQLite and PostgreSQL at 1M memories: BENCHMARKS.md. A recall that removes 10,000 memories takes about 5 ms, against 230 ms on SQLite and 1.73 s on PostgreSQL. Startup is slower: 679 ms against 0.1 ms on SQLite.
Install
go get github.com/govinargo-labs/cheesedb@v0.1.0
go install github.com/govinargo-labs/cheesedb/cmd/cheesedb@v0.1.0
Requires Go 1.26.5 or newer.
Known gaps
- Windows is not supported yet. The file lock works, but flushing the directory and replacing an open file during
Erasestill fail there. - No fuzzing or crash-injection tests yet.
- Developed on macOS; CI also runs the tests on Linux.
Full list of planned work: Roadmap.