How Mimir works

Mimir keeps what your agents learn in a database you own. A memory is a row with a path, a body and a title, and it belongs to one project. That is the whole model; everything else is a way to read those rows without blowing the agent’s context.

A project is a repository

An agent names its project with the X-Mimir-Repo: github.com/owner/repo header, or with a repo argument on a tool call. The first call creates the project; later calls from any client land in the same one. A project holds memories, members and grants, and nothing is shared between projects unless you grant it.

Paths are the index

Every memory has a path such as conventions/state-management or deploys/rollback. One path is one memory: writing it again replaces the body and keeps the old one as a version. Paths are compared case-insensitively and are literal, so auth scopes to auth and auth/… but never to authentication. Describe meaning in the path, not a file name — the path is what a search can scope to and what a person scans in the tree.

Every write keeps its predecessor

A write archives the body it replaces and trims that path’s history to the last 20 versions. A restore reads a version and writes it back as a new version with source restore, so a mistaken restore can itself be undone. Nothing in the interface deletes history; a delete soft-deletes the memory.

The digest is the session start

memory_digest answers “what do I already know here?” with no query and no embedding call. It reads the 200 most recently updated paths, gives titles to all of them, adds summaries to the newest five, groups them by the first path segment, and packs the result into 800 tokens by default. The agent pays for one cheap read and starts oriented.

Search is two arms and a fuse

A keyword arm over PostgreSQL full-text search and a vector arm over pgvector run on the same rows. Their ranked lists are fused with reciprocal rank fusion at k = 60, because a rank is a number both arms agree on. Without an embedding provider the vector arm is simply absent and search stays useful; the full explanation is in How search works.

Summaries come from your own model

With Learn from this project on, a background job asks your language model for a title and a one-line summary after a write, debounced so a burst of writes costs one call. A model that is down, slow or unconfigured never fails a write: the memory is stored, the keyword arm finds it at once, and the summary and vector arrive when the provider does.

People, teams and grants

Access	Can read	Can write
read grant	Tree, read, search, digest	No
write grant	Everything read grants	Write, delete, restore versions
project owner	Everything on the project	Settings, members, deletion

A grant names either a person or a team. Team membership is managed once and every project granted to the team follows it. An admin sees every project in the admin area but still needs a grant to read memories through MCP or the API.

The audit log

Auth, account, project, memory, provider, backup and admin actions write an audit row with the actor, the target and a small detail object — never a key, a token or a body. Rows for memory reads are kept 30 days; everything else 365. Admins can read the log under Admin → Audit, and prune the provider usage log separately under Admin → Usage.

Backups, and getting the data back

A scheduled run writes an encrypted pg_dump plus a settings export, reads both back to prove they are whole, and keeps the number of restore points you asked for. The restore path is documented in Backups and restore.

Your account

API keys under Settings → API keys mint the bearer token an agent uses for MCP and REST. The token is shown once; only its hash is stored. Revoke one and its next call fails.
Two-factor authentication under Settings → Security is per account and can be enforced for everyone by an admin. Losing the authenticator means an admin must reset MFA for you.
Your picture and name live under Settings → Profile. The avatar is stored on your account, so it follows you to another browser.

Where to go next

Providers and embeddings — which model does what, and what it costs.
Self-hosting — the compose file, environment and first admin.
HTTP API — the same operations without MCP.

text

project  ──  path  ──  memory (title, body, summary)
                  └── version 1..20
         └── grants (person or team, read or write)