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-remoteserver 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 binarycargo 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 --remoteclient wiring is part of the normal
kimetsu binary, so no separate install is needed to point a host at a server.
# On the server (build with --features embeddings for semantic retrieval):export KIMETSU_MCP_ENABLE_WRITE_TOOLS=1 # opt in to authenticated memory writeskimetsu-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:8787kimetsu 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.
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.
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.
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:
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.
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):
embedder
MRR
seq mean
rps
peak RSS
jina-v2-base-code
0.906
416ms
5.0
1.2 GB
bge-small-en-v1.5
0.909
700ms
3.8
697 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.
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):
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.
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.