Kimetsu
Kimetsu Network

Kimetsu Network

Share project memory across machines with a peer connection, signed packs, or directory sync. No server required.

Kimetsu Network

The Kimetsu Network is how two or more machines share the same project brain without a central server. Each machine keeps its own SQLite brain. You can move lessons between them in three ways:

  • Peer-to-peer — invite a machine, join with a code, then share and request a signed pack over a direct connection.
  • Directory sync — both machines write to the same shared folder (Dropbox, Syncthing, a NAS, or a USB stick).
  • Signed packs — export a file on one machine and import it on another.

Mounts say which scope a memory may live in. The peer path shares the repo mount only. MCP adapters wire your AI tool to the local brain on each machine.

This is separate from Kimetsu Remote, which is an HTTP server for a team brain.

Peer commands ship in v2.11.0. Prebuilt archives and npm install -g kimetsu-ai include them. cargo install kimetsu-cli from crates.io does not enable the network unless you pass --features network (Rust 1.91 or newer):

cargo install kimetsu-cli --features network

Check with kimetsu network status. If the command is unknown, the binary is older than v2.11.0 — use directory sync or a signed pack file below. A build without --features network answers that the peer network is not included; nothing is listening.

Install

Install the kimetsu binary on every machine that will share. Full details are in Install & host wiring.

# v2.11.0 or newer — lean prebuilt for your OS (network included)
npm install -g kimetsu-ai

# or, from crates.io, with the peer network compiled in (Rust 1.91+)
cargo install kimetsu-cli --features network

# or a GitHub Release archive from v2.11.0 onward
# https://github.com/RodCor/kimetsu/releases

cargo install kimetsu-cli from crates.io does not enable the network unless you pass --features network. v2.11.0 release and npm prebuilts include that feature; it stays off at runtime until you invite or join.

Check it:

kimetsu --version
kimetsu doctor
kimetsu network status

Quickstart: connect two machines (about two minutes)

This is the peer path. Run both sides in the same project directory. The two machines should be able to reach each other (same local network is the usual case). Published measurements are single-machine loopback. A two-machine figure is not recorded yet.

1. Install a network-enabled Kimetsu on both machines (see above) and init the project if you have not already:

cd /path/to/your/project
kimetsu init

2. On machine A, create a one-person join code:

kimetsu network invite --name laptop

Copy the code (it starts with knet1.). Treat it like a password. This command does not listen. The default name, if you omit --name, is friends. Names may use letters, numbers, -, and _.

3. On machine B, join:

kimetsu network join knet1.…

Membership is saved. Kimetsu is still not listening. Only the person who created the network can invite someone else.

4. Share from A, then request on B:

# on A — leave this running until B has finished
kimetsu network share
# it prints a line like:  peer: <endpoint-id>@host:port

# on B
kimetsu network request

If B cannot discover A on the local network, pass the peer: line that share printed:

kimetsu network request --peer <endpoint-id>@host:port

share listens until you press Ctrl-C, then nothing is listening. request verifies the pack signature before it writes anything.

5. Check, or leave:

kimetsu network status
kimetsu network leave

status never opens a socket. leave forgets this network on that machine.

Wire your AI tool so it reads the local brain:

kimetsu plugin install claude-code   # or: codex | cursor | grok-bot | pi | openclaw

Alternative: directory sync

The path that needs no UDP. It works on v2.11.0 and on older installs that do not have kimetsu network. Both machines write to the same shared folder.

# on machine A
kimetsu config set sync.dir /path/to/shared/kimetsu-sync
kimetsu config set sync.machine_id laptop

# on machine B
kimetsu config set sync.dir /path/to/shared/kimetsu-sync
kimetsu config set sync.machine_id desktop

sync.dir must be the same folder both can see. sync.machine_id must differ.

# on A
kimetsu brain memory add "prefer sqlx over diesel here" --scope repo --kind convention
kimetsu brain sync

# on B (after the shared folder has A's batch)
kimetsu brain sync
kimetsu brain memory list

Run kimetsu brain sync whenever you want a push/pull, or leave [sync] auto = true (the default once dir is set) so session end syncs for you. Check state with kimetsu brain sync --status.

Alternative: a signed pack file

When you only need to copy lessons once (onboarding, a USB stick, email):

# on A — make a signer key once (keep this file private)
python3 -c 'import secrets,json; print(json.dumps({"kimetsu_signer":1,"secret_key":secrets.token_hex(32)}))' > signer.json

kimetsu brain export team.json.gz --scope repo --name team --version 1.0.0 --sign-key signer.json

# on B — trust A's public key, then import
# (the pack's "signer" field is the public key; put it in ~/.kimetsu/trust.json)
kimetsu brain import team.json.gz --scope-override repo

Signed packs are kimetsu_pack 2. See Security for the trust store shape. Unsigned v1 packs still work for local files you trust.

What stays local

The peer path and signed packs move a scrubbed snapshot of repo memories only. Directory sync copies durable memory events (memory.accepted, memory.proposed, memory.rejected, memory.invalidated, memory.cited, memory.superseded, and a few related ones). None of these paths copy session resume text, run telemetry, embeddings, or the raw SQLite file. Your agent still talks to the brain over local MCP on each machine.

Words we use

WordMeaning
Kimetsu NetworkSharing project memory across machines (peer-to-peer, directory sync, or a pack file)
PeerAnother machine that has joined the same network
MountThe scope a memory may live in (repo, user, org, skill, session, run). The peer path shares repo only
PackA signed, scrubbed snapshot of memories
RosterThe signed list of who is on the network
Kimetsu RemoteA separate HTTP server for a team brain, not this peer path

Next

  • Results — what one brain adds, and what merged memory keeps, with the measurement caveats.
  • Connect your tools — MCP snippets for Claude Code, Codex, Cursor, and Grok Bot, plus the two network MCP tools.
  • Security — what is shared, what is signed, and when Kimetsu listens.
  • Troubleshooting — reachability, builds, sync folder, and pack import issues.
  • Reference — every kimetsu network command and flag.
  • Prefer a server instead? See Kimetsu Remote.

On this page