convez.ai
MCP Server
h-wata

kioku-mesh

h-wata/kioku-mesh

Ver no GitHub
InicialPluginScore · de 0 a 100

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-mesh

1 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

Estrelas
5
Forks
0
Acompanhando
1
Saúde
57%
Último commit
há 1 semana
Versão
v1.2.0
Issues abertas
7
Contribuidores
1

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

ModeUse it whenPersistenceExtra service
localYou want memory on one machineSQLitenone
hubThis machine is the always-on mesh hubRocksDBzenohd
spokeThis machine connects to a hubRocksDBzenohd

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:

VariablePurpose
MESH_MEM_AGENT_FAMILYAgent family, such as claude or codex
MESH_MEM_CLIENT_IDClient name, such as claude-code
MESH_MEM_SESSION_IDOptional stable session id
MESH_MEM_STATE_DIRState directory; defaults under the user data dir
MESH_MEM_BACKENDOverride the backend selected by ~/.config/kioku-mesh/config.yaml; set local or zenoh
MESH_MEM_FORCE_REBUILD=1Rebuild the local index at CLI startup
MESH_MEM_DISABLE_INDEX=1Use 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.
  • delete writes a tombstone. gc performs physical cleanup.
  • 0.x releases 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.

Ver o original no GitHub

Bom para

Relacionados