Kimetsu

Kimetsu Remote

Run the brain on a server and connect over HTTP MCP, so a team (or you across machines) shares one brain per repository, with no local checkout.

Kimetsu Remote (beta)

Run the brain on a server and connect over HTTP MCP, so a team (or you across machines) shares one brain per repository, with no local checkout.

Beta. Kimetsu Remote is under active testing and may have rough edges or breaking changes before the stable release. The kimetsu-remote server is a separate package: cargo install kimetsu-cli / npm i -g kimetsu-ai do not install it. Install it on the server when you want it:

npm install -g kimetsu-remote                       # prebuilt server binary
cargo install kimetsu-remote --features embeddings,tls,stores  # or from source

(or grab the standalone kimetsu-remote archive from a GitHub Release). The kimetsu plugin install --remote client wiring is part of the normal kimetsu binary, so no separate install is needed to point a host at a server.

Server + client setup

# On the server (build with --features embeddings for semantic retrieval):
export KIMETSU_MCP_ENABLE_WRITE_TOOLS=1  # opt in to authenticated memory writes
kimetsu-remote serve --addr 127.0.0.1:8787 --data /srv/kimetsu-brains \
  --token <secret> --rate-limit 120        # 120 req/min per token (0 = off)
#   one brain per repo under <data>/<repo-id>/; bearer-auth; plain HTTP. Put a
#   TLS proxy (nginx/Caddy) in front, or build `--features tls` and pass
#   --tls-cert/--tls-key for in-process HTTPS. `GET /healthz` and `GET /metrics`
#   (Prometheus text, aggregate-only) are unauthenticated. Prebuilt
#   kimetsu-remote binaries include embeddings, TLS and all storage providers.
#
#   Add --org-brain /srv/kimetsu-org for a shared team brain: memories recorded
#   at `global_user` scope land there and merge into EVERY repo's retrieval
#   (project-scoped memories stay per-repo). Must be outside --data.
#
#   Add --repos-file repos.toml --checkout-dir /srv/checkouts to let the server
#   clone registered repos and ingest their files (remote file-capsule retrieval).

# On each client, wire a host at the remote instead of the local stdio command:
kimetsu plugin install claude-code --remote https://kimetsu.example.com:8787
kimetsu plugin install openclaw    --remote https://kimetsu.example.com:8787

The repo id is derived from your git remote (--repo <id> to override), so the endpoint becomes https://…/mcp/<repo-id>. By default the host config references ${KIMETSU_REMOTE_TOKEN} (set that env var where your agent runs) rather than writing the token to disk. Pass --token <t> to embed a literal. The remote supports memory, retrieval and curation tools.

Write tools are disabled until the server process has KIMETSU_MCP_ENABLE_WRITE_TOOLS=1. Leave it unset or set it to 0 for read-only use. This opt-in enables recording/curation while preserving bearer auth and repo/global-token scope checks; a successful health check does not verify it.

Stateless servers and durable storage

Select --storage sqlite|postgres|redis|dynamodb to keep durable checkpoints in one database while each request uses a private, disposable SQLite retrieval projection. Containers and functions can be replaced without losing committed brain data. The SQLite store itself needs a persistent local volume; PostgreSQL, Redis and DynamoDB can serve independent instances sharing the same namespace.

export KIMETSU_REMOTE_STORAGE=postgres
export KIMETSU_REMOTE_DATABASE_URL='postgresql://USER:PASSWORD@DB/kimetsu?sslmode=require'
export KIMETSU_REMOTE_STORAGE_NAMESPACE=team
export KIMETSU_REMOTE_TOKEN='<secret>'
export KIMETSU_MCP_ENABLE_WRITE_TOOLS=1
kimetsu-remote serve --addr 127.0.0.1:8787

Use a TLS reverse proxy for this listener. Prefer injecting credentials through the environment. --database-url accepts a SQLite file path, PostgreSQL URL or Redis URL (rediss:// for TLS). DynamoDB uses KIMETSU_REMOTE_DYNAMODB_TABLE, the AWS region and the standard SDK credential chain. Its table needs string pk and sk keys; TTL on expires_at applies only to rate counters. Redis needs persistent storage, AOF with appendfsync always and maxmemory-policy noeviction; assess replication and failover durability separately.

--shared-org-brain enables org memory shared by every repo in the namespace. Use this within one trust group. Shared org writes and conflict resolution require a global token. Local-file mode retains --data and --org-brain PATH; checkpoint mode starts empty and does not import those directories automatically.

Changed repo and org checkpoints publish atomically against their previous revisions before a success response. Conflicting writers retry from fresh state; unavailable storage fails without a local fallback. Rate limits are shared, while metrics remain per instance. Whole checkpoints are transferred on requests: size memory, temporary disk and timeouts for representative brains. Each checkpoint is limited to 64 MiB compressed and 256 MiB decoded. Schema changes require an explicit migration or a compatible backup.

The separate kimetsu-remote-lambda binary uses the same authenticated router; build it with lambda and the selected storage feature. Lean builds keep serverless cold starts smaller; semantic builds retain the existing retrieval engine and add model-loading costs. DynamoDB builds currently need Rust 1.91.1+. See the storage configuration and operational limits and HTTP container / AWS SAM examples.

The Compose examples pass the write-tools flag through with default 0; export KIMETSU_MCP_ENABLE_WRITE_TOOLS=1 before starting them to enable writes. The SAM example likewise defaults closed: deploy with EnableWriteTools=1 to set the function's write-tools environment flag, or keep 0 for read-only use.

Team writes and attribution

Give each teammate their own bearer token (--token is repeatable, or use --tokens-file for a TOML of global and per-repo tokens). Writes are attributed to the token that made them, so memory blame on a shared brain answers who recorded what. Rate limiting is per token.

You can also write to the shared brain from the CLI without wiring a host:

kimetsu brain memory add "prefer sqlx over diesel here" \
  --remote https://kimetsu.example.com:8787 --repo my-org/my-repo

Concurrent writers are safe: the event log gives every write a stable order, conflicting facts are detected and resolved the same way as locally, and surviving conflicts are surfaced for review rather than silently dropped.

Retrieval quality

The server reranks kimetsu_brain_context results with a cross-encoder (--reranker, default jina-reranker-v1-tiny-en, operator-level: "off" disables, any curated/HF id accepted). Benchmark results on the 100-memory dataset (production floors active, jina-tiny reranker):

embedderMRRseq meanrpspeak RSS
jina-v2-base-code0.906416ms5.01.2 GB
bge-small-en-v1.50.909700ms3.8697 MB

The embedder is set per-repo via config or KIMETSU_BRAIN_EMBEDDER; the reranker is operator-owned and cannot be overridden by a repo's project.toml. See §7a "Retrieval models on the server" in HOW-KIMETSU-WORKS.md for the full table and how to re-run the benchmark.

Server-side ingest (optional)

To make file-capsule retrieval work remotely, let the server keep a managed clone of each repo. The operator pre-registers repos in a TOML file (so clients can't make the server clone arbitrary URLs):

# repos.toml
[repos]
github-com-org-api = { url = "https://github.com/org/api.git", branch = "main" }
github-com-org-web = "https://github.com/org/web.git"
kimetsu-remote serve --data /srv/kimetsu-brains --token <secret> \
  --repos-file /etc/kimetsu/repos.toml --checkout-dir /srv/kimetsu-checkouts

Then kimetsu_brain_ingest_repo clones/refreshes the registered repo and indexes its files into that repo's brain, so context retrieval includes file capsules. Private repos use the server's own git auth (credential helper / SSH / a token in the URL). The repo-id keys must match the ids clients connect with.

For the architecture (auth, rate limiting, org brain, the tool allowlist, the write-tools gate), see §7a in HOW-KIMETSU-WORKS.md.

Peer sharing instead of a server

If you want machines to share lessons without running kimetsu-remote, use kimetsu network (invite / join / share / request), signed packs, or directory sync on the Kimetsu Network page. The peer commands ship in the v2.11.0 prebuilt and npm binaries. Remote stays the HTTP checkpoint path; it does not dial the peer network.

On this page