kioku-mesh
h-wata/kioku-mesh
Shared memory for AI coding agents, across tools and machines. Local-first SQLite, optional Zenoh+RocksDB mesh, MCP-native.
Instalação
npx convez-ai h-wata/kioku-mesh1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
kioku (記憶) means memory.
kioku-mesh gives coding agents a shared memory store. 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
| Mode | Use it when | Persistence | Extra service |
|---|---|---|---|
local | You want memory on one machine | SQLite | none |
hub | This machine is the always-on mesh hub | RocksDB | zenohd |
spoke | This machine connects to a hub | RocksDB | zenohd |
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
kioku-mesh save "Decided to keep billing events append-only" \
--memory-type decision \
--importance 4 \
--subject billing
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:
| Variable | Purpose |
|---|---|
MESH_MEM_AGENT_FAMILY | Agent family, such as claude or codex |
MESH_MEM_CLIENT_ID | Client name, such as claude-code |
MESH_MEM_SESSION_ID | Optional stable session id |
MESH_MEM_STATE_DIR | State directory; defaults under the user data dir |
MESH_MEM_BACKEND | Override the backend selected by ~/.config/kioku-mesh/config.yaml; set local or zenoh |
MESH_MEM_FORCE_REBUILD=1 | Rebuild the local index at CLI startup |
MESH_MEM_DISABLE_INDEX=1 | Use the legacy Zenoh scan path instead of SQLite index |
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 its agents from a fast 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. The hub listens on addresses reachable from the 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
# hub
kioku-mesh init --mode hub \
--listen 127.0.0.1 \
--listen 192.168.3.10
# spoke
kioku-mesh init --mode spoke \
--listen 127.0.0.1 \
--connect 192.168.3.10
Mesh mode requires zenohd and zenoh-backend-rocksdb on PATH. The current
target is Zenoh 1.9.0.
zenohd -c ~/.config/kioku-mesh/zenohd.json5
For login auto-start on Linux systemd hosts, add --install-systemd to
kioku-mesh init --mode <hub|spoke> ...; the wrapper writes a user unit pointing
at the generated config.
kioku-mesh is designed to run inside a closed, trusted network. Keep port
7447/tcp reachable only between trusted peers. Do not expose it to the
internet or an untrusted LAN. By default kioku-mesh relies on network
admission (Tailscale, WireGuard, firewall rules, or a trusted LAN) rather than
transport-level authentication.
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
Run focused MCP checks with:
pytest tests/test_mcp_server.py tests/test_mcp_cli.py -v
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.
deletewrites a tombstone.gcperforms physical cleanup.0.xreleases are experimental; breaking changes can happen in minor versions.
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.