keepsake

module
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 20, 2026 License: MIT

README ΒΆ

🧠 Keepsake

Shared memory for fleets of agents.

Changelog

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.

How keepsake relates to other tools

  • 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

keepsake on Kubernetes

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.

Console overview

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.

Directories ΒΆ

Path Synopsis
cmd
keepsake command
Command keepsake operates an OKF knowledge store.
Command keepsake operates an OKF knowledge store.
Package frontend embeds the admin API contract the console's client is generated from.
Package frontend embeds the admin API contract the console's client is generated from.
internal
app
Package app is the composition root: it opens the database, builds the services and mounts the controllers.
Package app is the composition root: it opens the database, builds the services and mounts the controllers.
cli
Package cli is the operator commands, ported from 2de90d2:src/keepsake/cli/__init__.py.
Package cli is the operator commands, ported from 2de90d2:src/keepsake/cli/__init__.py.
controllers
The admin console's read-only JSON API at /api, ported from 8f2af2e:src/keepsake/server/api.py.
The admin console's read-only JSON API at /api, ported from 8f2af2e:src/keepsake/server/api.py.
migrate
Package migrate replays 8f2af2e:src/keepsake/store/migrations/versions/ without Alembic, through the same <schema>.alembic_version, so an Alembic-migrated database upgrades in place.
Package migrate replays 8f2af2e:src/keepsake/store/migrations/versions/ without Alembic, through the same <schema>.alembic_version, so an Alembic-migrated database upgrades in place.
models
Package models holds the values the repositories return.
Package models holds the values the repositories return.
pgtest
Package pgtest shares one Postgres container across a test run, one database per package, with the admin, owner and app roles of 2de90d2:tests/conftest.py.
Package pgtest shares one Postgres container across a test run, one database per package, with the admin, owner and app roles of 2de90d2:tests/conftest.py.
repositories
Concept writes, ported from 8f2af2e:src/keepsake/store/concepts.py.
Concept writes, ported from 8f2af2e:src/keepsake/store/concepts.py.
services
Bundles of markdown files in and out of Postgres, ported from 2de90d2:src/keepsake/cli/__init__.py.
Bundles of markdown files in and out of Postgres, ported from 2de90d2:src/keepsake/cli/__init__.py.
okf
Package okf is the Open Knowledge Format, publishable without the rest of keepsake.
Package okf is the Open Knowledge Format, publishable without the rest of keepsake.
internal/yaml
Package yaml implements YAML support for the Go language.
Package yaml implements YAML support for the Go language.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL