π§ Keepsake
Shared memory for fleets of agents.

Keepsake gives agents a durable, shared knowledge base they read and write over
MCP. It runs on Kubernetes, stores memory in Postgres, isolates tenants with
row-level security, and imports and exports plain markdown in the
Open Knowledge Format
(OKF).
MIT licensed. Self-hosted. Kubernetes-native.
Demo Β·
Deploy guide Β·
MCP tools Β·
Operations Β·
llms.txt
Ask an agent to evaluate it
Read https://raw.githubusercontent.com/roee-fs/keepsake/main/llms.txt and explain how keepsake would fit my current agent setup. If it fits, set it up with me.
llms.txt holds the same product and setup information in plain text.
Why keepsake
Agents lose everything when the context window closes. A file or a wiki carries
content, and nothing else. It does not keep two agents from overwriting each
other, it does not know which tenant a line belongs to, and nobody reviews what
agents wrote into it.
What keepsake provides:
- An MCP server. Seven bounded tools:
list, search, grep,
read, create, update, relate. Streamable HTTP, so a
fleet of pods shares one endpoint.
- Safe concurrent writes. One row per concept, keyed
(tenant_id, path).
Optimistic concurrency via an optional expected_version, so two agents
editing the same concept across an LLM call cannot silently clobber each
other β and agents editing different concepts never contend at all.
- Tenancy the database enforces. Row-level security picks the tenant from
the request. An agent never names a tenant, so it cannot name the wrong one.
- A Helm chart. Install with a managed CloudNativePG cluster, or point it at
a Postgres you already run and it installs into its own schema.
- An OKF bundle on the way in and out. The format is the interchange layer,
not the storage layer.
keepsake export regenerates index.md and log.md at
export time; they are never stored, so nothing derived can drift.
- A console. Operators review what agents stored, and who wrote it.
agent ββMCPββ> keepsake ββ> Postgres (RLS)
β
βββ keepsake import / export ββ> markdown bundle
See it work

What one agent learns, the next one knows. One command shows it:
git clone https://github.com/roee-fs/keepsake && cd keepsake && ./demo/run.sh
It needs Docker, kind, kubectl, Helm, jq and a
logged-in Claude Code.
It installs the chart on a throwaway kind cluster and imports
an on-call team's knowledge base. Agent A asks who to page before a Postgres
failover and gets a stale answer. Agent B, which just ran a failover drill, records
what it learned. Agent A asks again in a new session and gets the right answer and
the reason. The agents are real Claude sessions whose only memory is keepsake, over
MCP. Then it deletes the cluster.
Add --keep to leave the cluster up and point your own agent at it.
Try keepsake
Local
On your machine, with Docker only:
docker compose up -d
claude mcp add --transport http keepsake http://localhost:8000/mcp
The console is at http://localhost:8001, password keepsake. Load a bundle with
docker compose run --rm -v "$PWD/demo/bundle:/bundle:ro" keepsake keepsake import /bundle.
This setup is for trying keepsake out. It serves one tenant to anything that
reaches port 8000.
Kubernetes
helm install keepsake oci://ghcr.io/roee-fs/charts/keepsake --version 0.8.0
This also serves one tenant to anything that reaches the Service. For your own
Postgres and many tenants, follow the deploy guide.
Connect your agents
-
Claude Code: claude mcp add --transport http keepsake <url>/mcp.
-
Any MCP client that speaks streamable HTTP points at /mcp.
-
A client that can run code, or that only takes a static header, gets a
token for its own tenant:
kubectl exec deploy/keepsake -- keepsake token --tenant <uuid> --sub claude-code/2.1 --ttl 720h
The server sends the agent instructions with the tools: search before
answering, follow links, and update rather than duplicate.
docs/tools.md covers each tool's arguments and results.
- Model provider memory (Claude memory tool, OpenAI Agents SDK sessions,
Bedrock AgentCore Memory) is the fastest path inside one provider's stack.
The memory takes that provider's shape, so leaving means migrating it.
Keepsake stores markdown any agent can read.
- Memory products (Mem0, Zep and Graphiti, Letta) extract facts from
conversations for you. Mem0 takes a caller-supplied
user_id, Zep and
Graphiti take a group_id, and both filter on it β a single mis-set id
poisons a namespace permanently. Keepsake sets a Postgres GUC inside the
request transaction and lets row-level security do the enforcing.
- Databases with memory features (Redis, MongoDB, SurrealDB) leave the
memory model, tools, tenancy and review UI to you.
- Local and custom tools serve one developer or one repo, not a fleet
across tenants.
docs/alternatives.md says when to choose each instead.
Tenancy and authority
| Decision |
Simple option |
Production option |
| Who picks the tenant |
auth.mode: none. One tenant, auth.fixedTenantId, for anything that reaches the port. |
auth.mode: jwt. A signed token per request. Its tctx.tenant claim picks the tenant. |
| Where data lives |
postgres.mode: managed. A CloudNativePG cluster the chart creates. |
postgres.mode: existing. Your Postgres, in its own okf schema. |
| Who signs tokens |
keepsake token, for a client that takes a static header. |
Your orchestrator, with a short-lived token per call. |
In jwt mode each /mcp request carries an HS256 bearer token. Your
orchestrator holds the signing secret. The HMAC key is the line's text as-is,
not its hex-decoded bytes:
{"iss": "platform", "aud": "keepsake", "sub": "support-agent/1.4", "tctx": {"tenant": "<uuid>"}, "exp": β¦}.
keepsake records sub as the writer, and stamps it as OKF generated.by on every
concept the token writes through /mcp. It MUST be an OKF Β§7 actor: <producer>/<version>
for an agent, human:<id> for a person or process:<id> for a process.
keepsake token refuses anything else.
A token whose space-separated scope claim includes read, such as
"scope": "read", is read-only: create, update, relate and PUT /bundle
refuse it. A token without read keeps every write. An orchestrator SHOULD
mint read tokens for agents that only consult keepsake.
The secret MUST NOT be readable by anything an LLM drives.
The server refuses to start if it is connected as a superuser or as the schema
owner, because both silently bypass RLS.
How it works

Agents call the Service over MCP, and operators use the console through the
same Service. A Helm hook runs the migration Job before every install and
upgrade.
Versioning
Every write gives a concept a new version, drawn from one sequence that never
repeats. It only grows, and gaps are normal. Every write also appends a
revision: who wrote what, and when. Deletes are revisions too, so a deleted
concept's history stays readable.
To edit safely, an agent passes the version it read back as
expected_version. If anyone wrote the concept since, the write changes nothing
and the agent gets the current version and body to merge against. An import
skips unchanged concepts, so pushing the same bundle twice changes nothing.
The console
The chart serves a read-only admin console from the same pod as /mcp, on its
own port, 8001. Port 8000 serves only /mcp, /bundle and /readyz, so a
NetworkPolicy MAY open one without the other. Helm generates the password at
install, into a <release>-admin Secret:
kubectl get secret <release>-admin -o jsonpath='{.data.password}' | base64 -d
kubectl port-forward svc/<release> 8001:8001
Then log in at http://localhost:8001 with that password.

What is in this repository
| Path |
Responsibility |
cmd/keepsake |
The one binary: serve, migrate, import, export, validate, token. |
internal/app |
Wires the database, services and controllers into the served app. |
internal/controllers |
The MCP server, the console API, bundle uploads and auth. |
internal/services |
Tool, console and bundle logic. |
internal/repositories |
Tenant-scoped reads and writes, search, and the revision log. |
internal/models |
The rows repositories return and the errors every layer matches on. |
internal/migrate |
The schema, RLS policies and grants. |
internal/cli |
The CLI commands. |
okf/ |
OKF parsing, serialization, links and validation. |
frontend/ |
The console, embedded in the binary. |
charts/keepsake |
The Helm chart. |
demo/ |
The two-agent demo and its bundle. |
e2e/, tests/ |
The kind end-to-end suite and the chart and release checks. |
bench/ |
Agent and search benchmarks. bench/README.md lists them. |
Documentation
Current limitations
- Pre-release. Nothing here is stable yet.
jwt mode verifies HS256 tokens with a shared secret only. OIDC and
Kubernetes ServiceAccount tokens are not supported yet.
- Search is lexical (BM25). There is no semantic search yet.
- There are no per-tenant rate limits.
- Keepsake does not deduplicate concepts or resolve contradictions.
- The chart configures no backups. See
docs/operations.md.
Contributing
CONTRIBUTING.md has the setup, the checks CI runs, and what
a good change looks like. go test ./... is the whole loop; the tests bring up
PostgreSQL in a container themselves.
Found something touching tenant isolation? SECURITY.md β report
it privately, not as an issue.
Participation is covered by the Code of Conduct.
License
MIT β see LICENSE.