Skip to content

Releases

v0.3.0 (preview): search by meaning, and recall that asks first

Choose a tag to compare

@govinargo govinargo released this 16 Nov 13:39
f402e1c

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, VerifyIndex and DropIndex.
    • 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. Erase and Compact remove 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:

  • remember stores a vector with each memory, and MCP apps get a search tool.
  • New commands:
    • cheesedb search finds memories by meaning.
    • cheesedb embed makes existing memories searchable, or rebuilds the index after a model change.
    • cheesedb index manages the indexes.
  • cheesedb ask searches 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 learn makes what it learns searchable, so another app sharing the same memory finds it.
  • cheesedb find now 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:

  1. 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.
  2. 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, get and list_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: recall now 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-search runs offline, or against a real embedding model.
  • examples/plain-english walks 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.

See the changelog and Limits.

v0.2.0 (preview): now with an MCP server

Choose a tag to compare

@govinargo govinargo released this 02 Nov 15:32
b1dd18f

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)

v0.1.1 (preview) Pre-release
Pre-release

Choose a tag to compare

@govinargo govinargo released this 30 Oct 13:59
7bb443c
updated the website url (#35)

Signed-off-by: govinargo <156787779+govinargo@users.noreply.github.com>

v0.1.0 (preview)

v0.1.0 (preview) Pre-release
Pre-release

Choose a tag to compare

@govinargo govinargo released this 29 Oct 16:31

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. Fair and Strict recall of a source or a memory, plus Get and Active.
  • 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 cheesedb command: every feature from the command line, plus a demo with a real LLM that compares a plain memory list, Untrusted and Erase.
  • 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 Erase still 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.