kioku-mesh 1.1.0

A shared memory mesh for AI coding agents — across every tool and machine you own.

kioku (記憶) means memory.

kioku-mesh gives coding agents a shared memory mesh. Claude Code, Codex CLI, Gemini CLI, and other MCP clients can save and search the same observations from one machine or from several machines on a trusted LAN/VPN mesh.

The default setup is local and needs no daemon. Mesh mode is available when you want the same memory pool replicated between hosts.

Why kioku-mesh

Coding-agent context gets fragmented across machines: which laptop did that work, what did the agent on the other host decide, and why does a secondary agent have to re-read everything from scratch just to give a quick second opinion? kioku-mesh keeps that memory in one shared pool so any agent, on any of your machines, can recall it.

Unlike long-term memory tools that store everything in one place, the shared pool is a peer-to-peer mesh you run yourself across your own machines (LAN / VPN / Tailscale) — no SaaS, no central account. The same memory is readable by Claude Code, Codex CLI, Gemini CLI, and any other MCP client.

Quickstart

uv tool install kioku-mesh
# or: pip install kioku-mesh

kioku-mesh init --mode local
kioku-mesh save "Chose Postgres over SQLite for analytics"
kioku-mesh search "Postgres"

Install the MCP server for your agent:

kioku-mesh mcp install --client claude-code
kioku-mesh mcp install --client codex-cli

The package installs two commands:

• kioku-mesh: the CLI.
• kioku-mesh-mcp: the stdio MCP server launched by your agent.

Modes

local is the default and the easiest starting point. Re-run kioku-mesh init --mode <mode> --force when you want to switch. For a short-lived Zenoh smoke test without provisioning anything, use kioku-mesh mesh start.

In mesh mode the Zenoh/RocksDB store is the source of truth, and each host's SQLite is a fast local read cache rebuilt from it — not a separate copy you have to reconcile. local mode is a standalone, SQLite-only setup for a single machine, so its saves live only in that local store and are not replicated to a mesh.

CLI

# --subject and --summary are required
kioku-mesh save "Decided to keep billing events append-only" \
  --memory-type decision \
  --importance 4 \
  --subject billing \
  --summary "billing events stay append-only"

kioku-mesh search "billing events"
kioku-mesh get-memory <observation_id>
kioku-mesh delete <observation_id>
kioku-mesh gc --retention-days 30
kioku-mesh doctor

Useful environment variables (the MESH_MEM_ prefix was renamed to KIOKU_MESH_ in ADR-0024; only KIOKU_MESH_* is read as of v1.0.0):

Troubleshooting variables (KIOKU_MESH_FORCE_REBUILD, KIOKU_MESH_DISABLE_INDEX, KIOKU_MESH_SKIP_REBUILD, KIOKU_MESH_INDEX_DB) are documented in docs/Spec.md.

Visibility migration

If you have observations written before v0.8 (legacy layout mem/obs/**):

kioku-mesh doctor --check-legacy-namespace              # 1. check what remains
kioku-mesh migrate-visibility --from legacy --to mesh   # 2. migrate
kioku-mesh doctor                                       # 3. confirm zero legacy obs/tomb

As of v1.0.0 (ADR-0029), KIOKU_MESH_LEGACY_WRITE_EMERGENCY and KIOKU_MESH_LEGACY_READ_FALLBACK are removed and have no effect.

Visibility scopes

--visibility (CLI) / visibility (MCP save_observation) controls how far a memory replicates: user (your machines only, needs user_id), team (peers hosting that team's storage, needs team_id), or mesh (every peer, the default). Ids are resolved server-side, never from tool args — see ADR-0019.

A per-project default can be set via .kioku-mesh.yaml (searched upward from the cwd; env vars win, the global config is the fallback). Only default_visibility / team_id may be set this way, never user_id — a committed file must not set a personal namespace. Every save response echoes the effective scope, e.g. saved: <id> (visibility=team/kioku-mesh).

MCP Clients

kioku-mesh mcp install handles the common setups:

kioku-mesh mcp install --client claude-code
kioku-mesh mcp install --client codex-cli

For Claude Desktop, Gemini CLI, ChatGPT Desktop, manual JSON/TOML examples, SessionStart hooks, and multi-agent identity recipes, see docs/mcp-clients.md and docs/multi-agent.md.

Multi-Host Mesh

Each host serves agents from a local SQLite read index backed by a Zenoh router + RocksDB store, and hosts replicate to each other over the mesh:

flowchart LR
  subgraph HostA["🖥️ Host A"]
    direction TB
    A1["Claude Code"]
    A2["Codex CLI"]
    AS[("SQLite index<br/>local read path")]
    AZ["zenohd<br/>Zenoh router + RocksDB<br/>(source of truth)"]
    A1 & A2 -->|"save / search"| AZ
    AZ -->|"subscriber · rebuild"| AS
    A1 & A2 -.->|"fast reads"| AS
  end
  subgraph HostB["🖥️ Host B"]
    direction TB
    B1["Codex CLI"]
    B2["Gemini CLI"]
    BS[("SQLite index<br/>local read path")]
    BZ["zenohd<br/>Zenoh router + RocksDB<br/>(source of truth)"]
    B1 & B2 -->|"save / search"| BZ
    BZ -->|"subscriber · rebuild"| BS
    B1 & B2 -.->|"fast reads"| BS
  end
  AZ <==>|"Zenoh mesh replication<br/>LAN / VPN / Tailscale · TCP 7447"| BZ

The recommended topology is one hub and any number of spokes: every spoke dials only the hub.

flowchart TB
  HUB["⭐ Hub<br/>always-on peer<br/>listens on LAN / Tailscale / VPN"]
  S1["Spoke · laptop"]
  S2["Spoke · desktop"]
  S3["Spoke · CI / server"]
  S1 -->|"dials hub (TCP 7447)"| HUB
  S2 -->|"dials hub"| HUB
  S3 -->|"dials hub"| HUB
  S1 -.->|"router transit<br/>(no direct link)"| S3
  S2 -.->|"router transit"| S3

# 1. Install zenohd + zenoh-backend-rocksdb (default: ~/.local/share/kioku-mesh/bin/)
kioku-mesh zenohd install
export PATH="$HOME/.local/share/kioku-mesh/bin:$PATH"  # persist in ~/.bashrc or ~/.zshrc

# 2. Generate config (add --install-systemd for a login-time auto-start unit)
kioku-mesh init --mode hub --listen 127.0.0.1 --listen 192.168.3.10     # hub
kioku-mesh init --mode spoke --listen 127.0.0.1 --connect 192.168.3.10 # spoke

# 3. Without --install-systemd, start zenohd manually:
zenohd -c ~/.config/kioku-mesh/zenohd.json5

Docker (zenohd)

If Docker is available, docker compose up -d starts zenohd + RocksDB without an apt install or touching src/kioku_mesh/. Data persists under ./data/zenoh/; the default docker-compose.yaml publishes ports on all interfaces (0.0.0.0) — restrict to 127.0.0.1 or a trusted network. Backups, connecting other peers, and upgrading Zenoh are covered in docs/zenohd-docker.ja.md.

Prefer not to use Docker? kioku-mesh zenohd install auto-detects your arch/OS and installs a checksum-verified zenohd + RocksDB plugin (or place the binaries on PATH yourself for an offline install). kioku-mesh mesh start runs an in-process Zenoh router for a smoke test — no binary required.

kioku-mesh is designed to run inside a closed, trusted network — keep port 7447/tcp reachable only between trusted peers, never an untrusted LAN or the internet. By default it relies on network admission (Tailscale, WireGuard, firewall rules) rather than transport-level auth.

When network admission alone is not enough, enable mutual TLS: every peer presents a certificate signed by your own private CA, and zenohd refuses any unverified link. Each peer's private key is generated locally and never leaves the host — only CSRs and signed certs (all non-secret) are exchanged.

kioku-mesh tls init-ca                            # once, on the CA host
kioku-mesh tls enroll <ca-host> --san <this-ip>   # on each peer (needs SSH to the CA host)
kioku-mesh init --mode <hub|spoke> --tls --listen ... --force

No SSH? The copy-paste flow works over any channel: tls request prints a CSR block, paste it into tls sign on the CA host, paste the bundle it returns into tls install. The peer key never leaves the host; only non-secret blocks move.

See docs/mtls.md for the full walkthrough, the trust model, and certificate rotation.

For a full walkthrough with firewall notes, five-peer examples, add/remove procedures, and smoke tests, see config/peers/example_5peer.md.

Development

pip install -e '.[dev,test]'
pytest tests/ -q
pytest tests/test_mcp_server.py tests/test_mcp_cli.py -v  # focused MCP checks

Notes

• Python 3.10+ is required.
• Linux is the primary development and deployment target.
• Windows users should prefer WSL2. Native setup notes are in docs/windows-setup.md.
• macOS support is not verified yet.
• delete writes a tombstone. gc performs physical cleanup.
• 0.x releases are experimental; breaking changes can happen in minor versions. From 1.0.0 onward, the public CLI / MCP / Python API and on-disk schema follow Semantic Versioning: breaking changes require a semver-major bump or an explicit migration path (ADR-0029).

More detail lives in docs/Spec.md, CHANGELOG.md, and the design records under docs/adr/.

Acknowledgments

kioku-mesh was influenced by engram and claude-mem. No code is copied from either project.