kaeru

# 蛙 kaeru `kaeru` is a **cross-agent cognitive engine** for LLM agents — a typed graph that agents think in, plus a recollection layer for long-term ideas and outcomes. Local-first for each agent, with an optional shared cloud tier so a whole team of agents and people build on one another's memory. Designed for **multi-session, multi-agent continuity**: when an agent opens a project, it has full context of what was being thought about, can follow provenance chains, can consolidate outcomes into stable long-term knowledge, and can pull in what the rest of the team has shared. Inspired by the LLM-wiki pattern (Karpathy, gist `442a6bf555914893e9891c11519de94f`), the bi-temporal knowledge graph approach of Graphiti / Zep, the curator-driven knowledge engine of Cognee, and the reasoning-based hierarchical-summary navigation pattern from PageIndex. Two-tier design grounded in the hippocampus / cortex split. Name: 蛙 (*kaeru*, "frog"; homophonic with 帰る "to return" and 変える "to change") — the agent that returns, recalls, and reshapes.  _{A kaeru vault rendered by [`kaeru-viz`](kaeru-viz/) — one cluster per initiative, nodes sized by memory layer, with reasoning-chain replay and a time-lapse of how the knowledge grew.} ## Overview `kaeru` is built around a typed property graph stored in CozoDB. Two tiers, biological analogy: - **cognitive (operational / hippocampus)** — high-velocity working graph where the agent actively thinks: episodes, scratch, drafts, hypotheses, experiments, audit events. - **recollection (archival / cortex)** — settled ideas, outcomes, summaries, references; mostly read. Every node and edge is **bi-temporal** — the substrate stores assertion / retraction history natively, so time-travel queries are out of the box and conflict resolution is non-destructive (the old version is invalidated, not deleted). Per-initiative subgraphs through a junction-relation pattern: one substrate, many initiatives, multi-membership. An agent working on project A asks "what was I doing here last time?" and gets an answer scoped to A. The same node can belong to several initiatives at once. `kaeru` is a **facilitator, not an enforcer**. The curator API exposes ~40 primitives (`awake`, `recall`, `drill`, `claim`, `synthesise`, `at`, `history`, `consolidate_out`, …) as available tools. The agent and user choose when to invoke them; the daemon hints but doesn't block. ## Features - **Two-tier graph** — operational (cognitive / hippocampus) for active thinking; archival (recollection / cortex) for settled knowledge. `consolidate_out` promotes across the boundary, preserving provenance. - **Bi-temporal** — native assertion / retraction history. `at` reads a node in full as it is now or as-of any past moment; conflicts are non-destructive (the old version is invalidated, not deleted). - **Per-initiative scoping + layered re-entry** — one substrate, many projects. `awake` restores a project's working context by memory layer (Core → Hot → Warm); `surface` reaches the archived Cold / Frozen on demand. - **Cross-agent sharing** — local-first by default; an optional `kaeru-cloud` tier lets a trusted team share settled knowledge through two safety gates (initiative policy + a deterministic secret guard). See [Local & cloud](#local--cloud--sharing-memory-across-a-team). - **Structural recall** — exact name lookup, typed `walk` / `drill` / `trace`, `between`, FTS fuzzy fallback. Vectors are not the primary mode. - **Initiative management** — `rename` / `delete` an initiative, locally or team-wide. - **Markdown export** — Obsidian-friendly snapshot of any initiative. ## Architecture Notes - **Substrate is CozoDB** with RocksDB backend; bi-temporal `Validity` is native to the substrate, not bolted on. - **Edges carry operational semantics** — each edge type is something the curator API responds to. `derived_from` powers provenance and explainability; `contradicts` triggers a non-destructive `under_review` flow; `supersedes` retracts the previous version through the bi-temporal substrate. Edges are not just associations. - **`audit_event` is a first-class node type** — every mutation writes an audit node, so changes to memory themselves become reasoning surface for the agent. Substrate-level history (`Validity`) and operational audit (audit-event nodes) stay separate: the substrate tracks *what was*, the audit nodes track *who did it and why*. - **Per-initiative scope through junction relations** rather than column filtering — RocksDB prefix-scan gives O(log n + k) on the active initiative. - **Retrieval is structural-first** — explicit name lookup, typed graph traversal, summary views. Cozo FTS for fuzzy fallback when an exact name is forgotten. Vector embeddings are not the primary mode. - **Two-tier with explicit `consolidate_out`** — operational drafts get promoted to archival as a deliberate, logged operation. Provenance (`derived_from`) survives the tier boundary. - **Single binary, embedded substrate** — `kaeru` runs in-process with the agent. No server, no network. Vault on disk under a platform-specific default (Linux `$XDG_DATA_HOME/kaeru`, macOS `~/Library/Application Support/ai.lamantin.kaeru`, Windows `%LOCALAPPDATA%\ai.lamantin.kaeru`); override with `KAERU_VAULT_PATH`. ## Layout ``` kaeru/ ├── Cargo.toml ← workspace root ├── kaeru-core/ ← library: substrate, schema, primitives ├── kaeru-mcp/ ← binary `kaeru-mcp`: Model Context Protocol server (the agent's surface) ├── kaeru-cloud/ ← binary `kaeru-cloud`: shared cloud tier (Axum REST over kaeru-core) ├── kaeru-rig/ ← library: `rig` Tools that give a rig agent kaeru memory └── skills/ └── kaeru-skill/ ← portable agent skill (Claude Code / etc.) ``` `kaeru-rig` is the [rig](https://github.com/0xPlaygrounds/rig) framework adapter — the full curator verb set as discrete rig `Tool`s over an embedded `Arc<Store>`, so a rig agent reads and writes one vault. Future: `kaeru-langchain` (Python bridge), not yet started. ## Install > **Pre-1.0 alpha.** Substrate schema may change between minor versions — > export to markdown if you need to keep notes around. See [QUICK_START.md](QUICK_START.md) for source builds, MCP daemon setup, and the re-entry ritual. ## Quick tour (MCP tools) ``` # See what projects exist: initiatives # Re-entry ritual: process state + epistemic state. awake (initiative: "auth-rewrite") overview (initiative: "auth-rewrite") # Capture (auto-named): jot (initiative: "auth-rewrite", body: "noticed token expiry differs across platforms") # Fuzzy lookup when you forgot the exact name: search (initiative: "auth-rewrite", query: "expiry") # Drill into something: drill (initiative: "auth-rewrite", name: "noticed-token-expiry-differs-across-...") # Hypothesis cycle: claim (initiative: "auth-rewrite", body: "platform-aware policy is correct", about: "<node>") test (initiative: "auth-rewrite", hypothesis: "<hyp>", method: "compared iOS / Android TTL") confirm (initiative: "auth-rewrite", hypothesis: "<hyp>", by: "<experiment>") # Time-travel: at (initiative: "auth-rewrite", name: "<name>", when: "5m") history (initiative: "auth-rewrite", name: "<name>") # Knowledge chains — strongest weighted path between two nodes # (link the load-bearing edges with strong: true first): path (initiative: "auth-rewrite", from: "<a>", to: "<b>") # preview the trail chain (initiative: "auth-rewrite", from: "<a>", to: "<b>") # save it as a recallable chain # Snapshot to an Obsidian-friendly markdown vault: export (initiative: "auth-rewrite", path: "/tmp/auth-snapshot") ``` ## Connecting to an MCP-aware agent `kaeru-mcp` is a long-lived HTTP service: **one daemon per machine** owns the substrate, any number of agent sessions (Claude Code, Opencode, Cursor, …) connect concurrently. This is intentional — RocksDB is single-writer, so a stdio MCP that forks a subprocess per session would hit lock contention. See `kaeru-mcp/README.md` for systemd / launchd unit templates and the full HTTP config. Run the daemon (or set up the systemd user unit from `contrib/install/`): ```bash kaeru-mcp # foreground, Ctrl-C to stop ``` Then point your agent at it: - **Claude Code**: `claude mcp add --transport http kaeru http://127.0.0.1:9876/mcp` — see `skills/kaeru-skill/` for the portable system-prompt rules. - **Opencode**: `bash contrib/opencode/install-opencode.sh` — wires the daemon, drops `AGENTS.kaeru.md` rules into `~/.config/opencode/`, and installs `/kaeru` / `/lesson` / `/recall` slash commands. Designed to coexist with your existing OSS-model provider config (Qwen / DeepSeek / GLM / Ollama). See `contrib/opencode/README.md`. - **Cursor and other runtimes**: paste the body of `skills/kaeru-skill/SKILL.md` into your agent's rules / system-prompt section. For MCP-aware clients the daemon URL above works directly. After restart the agent sees tools like `awake`, `drill`, `claim`, `at` natively. Each tool takes an optional `initiative` parameter. ## Local & cloud — sharing memory across a team `kaeru` runs **local-first**: your vault lives on your machine and nothing leaves it by default. A second, optional tier — `kaeru-cloud` — is a shared store for a trusted group (a team, a family). Each initiative carries a sticky `share_policy`: - `private` (default) — nothing ever leaves; personal projects. - `team` — nodes you explicitly mark `shared` may sync to the cloud. Sharing is never automatic and passes two gates: the initiative policy, and a deterministic **pre-share secret guard** that blocks anything looking like an API key, token, or private key. The guard is silent on clean content and only interrupts on a real hit. Verbs (over MCP): `policy` (mark an initiative `team`), `share` (push a node), `cloud_recall` (see what the team has), `pull` (bring a shared node into your local graph), `link_cloud` / `cloud_links` (reference cloud nodes without copying), and `sync_review` (batch-review still-local nodes). Capture verbs (`episode` / `jot` / `cite`) take `visibility: shared` to capture-and-share in one call. A single daemon can also reach **several named clouds** (e.g. a `family` and a `work` cloud) via a `clouds.toml` file; the cloud verbs then take an optional `cloud: <name>` and soft links remember which cloud they point at. See [`kaeru-mcp/README.md`](kaeru-mcp/README.md#configuration) for the file format. Per-user / per-org isolation (multi-tenant) is a future addition; today each cloud is one shared space scoped by initiative. See [`kaeru-cloud/README.md`](kaeru-cloud/README.md). ## Roadmap - **Initiative onboarding** — a generated "what is this initiative, and what's in it" briefing the first time an agent enters a project, in the spirit of the `import` guide — an instruction over the collected context, not graph machinery. - **PostgreSQL backend** — a server-mode substrate alongside the embedded RocksDB default. - **Multi-tenant + isolation** — per-user / per-org separation in the shared cloud. - **Cross-initiative links** — edges and recall that span initiatives (everything is initiative-scoped today). ## Status Pre-1.0. Implemented and covered by a green test suite: the substrate and curator API, memory layers with layered re-entry (`awake` / `surface`), bi-temporal time-travel (`at` / `history`), per-initiative scoping with `rename` / `delete`, knowledge chains (weighted edges + shortest-path), forward-only schema migrations, the MCP server, the shared `kaeru-cloud` tier (sharing, recall, soft links, sync-review) including multi-cloud, the `kaeru-rig` framework adapter (full curator toolset as rig Tools), and markdown export. What still needs hardening: - **Multi-tenant.** The cloud is one shared space scoped by initiative; per-user / per-org isolation isn't built yet. - **MCP concurrency.** Concurrent sessions share one `Store`; the per-call initiative scope is serialized through `Store::scoped`, so two sessions can't corrupt each other's scope. What remains is ordering — when an agent batch-fires async calls, a read can still land before a not-yet-applied write. - **Whole-second `Validity` resolution.** Two opposing mutations on the same node/edge within one second (e.g. `link` then an immediate `unlink`, or a `forget` right after a write) resolve ambiguously. Interactive use is fine — human pacing always crosses the boundary; the test suite sleeps between such operations. - **Audit events** aren't attached to the initiative junction yet (export filters them by `affected_refs` intersection — a working workaround). - **Rig adapter shipped, LangChain not yet.** `kaeru-rig` gives a [rig](https://github.com/0xPlaygrounds/rig) agent the full memory toolset; a Python / LangChain bridge is still to come. - **Migrations are forward-only and add-only.** A `migration_journal` runs schema additions (new relations / columns) on open; there is no down-migration or destructive-change path yet. Snapshot via `export` before a major upgrade is still prudent pre-1.0. ## Contributing Discussion and design feedback through issues. PRs welcome on the open items above and anywhere the agent-facing surface feels rough — the verb taxonomy (`awake`, `drill`, `claim`, `flag`, `settle`, …) is meant to map to natural agent thinking, not just expose graph operations. ## License MIT — see `LICENSE`.