kaeru

Purpose

kaeru is a cognitive memory engine designed for LLM agents, with the goal of solving the continuity problem in multi-session, multi-agent collaboration. When an agent reopens a project, it can obtain full context: what was thought before, how tasks are progressing, which assumptions remain to be verified, and which conclusions have settled. The name "kaeru (frog)" is a homophone of the Japanese "帰る (return)" and "変える (change)," implying that agents can return, recall, and reshape knowledge.

Main Capabilities

Dual-layer graph structure: The cognitive layer (operations/hippocampus) carries the high-speed working graph, including episodes, drafts, hypotheses, experiments, and audit events; the recall layer (archive/cortex) stores stabilized ideas, outcomes, summaries, and citations, and is mainly for reading.settle Promote nodes that have stopped changing to the archive layer, preserving provenance.

Bitemporal history: Each node and edge natively records assertion/retraction history,at Nodes can be read as of the current or any past moment, and conflict resolution is non-destructive—old versions are marked invalid rather than deleted.

Layered re-entry by project:awake Restore the project working set by memory tier (Core → Hot → Warm), while also presenting the stable knowledge in the archive cortex, so that durable facts can re-enter at every session;surface The archived Cold/Frozen layers can be reached on demand.

Reasoning chains:chain Save the weighted path between two nodes as a recallable trajectory, together with an agent-written summary;why Read trajectories. Duplicates are collapsed on creation,rechain and trajectories can be refreshed after the graph changes.

Self-maintenance:reflect Compute a curation checklist (orphan nodes to link, overdue tasks, stale chains, settled work to promote to the cortex, shared/cloud rebalancing items requiring user intervention). The background hygiene process automatically adjusts node tiers when accumulated triggers occur, and is enabled by default.

Role slots:slot Give a project a role held by exactly one active node (such as handoff point, entry point, or queue); when replaced, the old node is archived to Cold and linked with supersedes, avoiding multiple "current" handoff points in a project.

Version reminders: The daemon checks GitHub once a day for a new version, and if there is one, the next awake will state the current version, how many releases behind it is, a one-line reason for that release, and the upgrade command for the corresponding installation method. The agent is the upgrader and will ask before executing. Only one public GET, no identifiers, can be KAERU_MCP_UPDATE_CHECK=0 disabled.

Cross-agent sharing: Local-first, with an optional kaeru-cloud layer that lets trusted teams share settled knowledge, through two safety gates (project policy + deterministic secret guard).cloud_recall Search the shared layer,unshare Retract errors; when multiple clouds are configured, an unnamed call is rejected rather than routed to a default.

Structured recall: Exact name lookup, typed traversal walk/drill/trace、between, FTS fuzzy fallback. Every read carries the node assertion time; reads that are not exact matches suggest verbs for going deeper. When a name cannot be resolved, it states one of three cases: it exists in another project, a similar item exists, or it does not exist.

Readback on re-entry:awake Restore what has been touched and what is still pending: overdue tasks first, claims awaiting adjudication, saved traces and their summaries. Shared projects will indicate that local answers may be incomplete.

Other: project management (rename/delete projects, attach nodes to other projects), Markdown export (Obsidian-friendly snapshots).

How to use

kaeru runs as a single binary, embedding CozoDB (RocksDB backend) underneath, with the vault being a local file tree. The daemon kaeru-mcp is a long-running HTTP service; one daemon per machine owns the underlying storage, and any number of agent sessions (Claude Code, Opencode, Cursor, etc.) can connect concurrently—this is because RocksDB is single-writer, and forking a child process per session over stdio MCP would run into lock contention.

Connecting MCP agents:

• Run the daemon (or use the systemd user unit in contrib/install/)
• Claude Code:claude mcp add --transport http kaeru http://127.0.0.1:9876/mcp, see also the portable system prompt rules in skills/kaeru-skill/
• Check memory first (Claude Code and Codex): contrib/hooks/kaeru-first/ is a harness hook for when the agent is about to ask the user a question; if kaeru has not been read recently, it first makes the agent search once, then captures the user's answer
• Opencode:bash contrib/opencode/install-opencode.sh, which connects to the daemon, places the AGENTS.kaeru.md rules into ~/.config/opencode/, and installs the /kaeru, /lesson, /recall slash commands
• Cursor and other runtimes: paste the body of skills/kaeru-skill/SKILL.md into the agent's rules/system prompt section; MCP-aware clients can use the daemon URL above directly

After a restart, agents can natively see awake、drill、claim、at and other tools, each accepting an optional initiative parameter.

Building without network: some machines cannot access crates.io; the dependencies for each release are vendored into a separate repository, LamantinAI/kaeru-vendor, with one tag per release. Whether online or offline, cozo builds RocksDB from C++ and zstd/lz4 from C, so a C++ toolchain and libclang are required; see docs/offline-build.md for details.

Local and cloud: local-first by default, with the vault on the user's machine and by default never leaving it. An optional second layer, kaeru-cloud, is available for trusted groups to share. Each project carries a sticky share_policy: private (default) never leaves; team allows nodes explicitly marked as shared to sync to the cloud. Sharing is never automatic; it must pass through two gates: the project policy and a deterministic pre-shared secret guard. Related verbs:policy、share、cloud_recall、pull、link_cloud/cloud_links、sync_review. The capture verb (episode/jot/cite) accepts visibility: shared to capture and share in one step. A single daemon can access multiple named clouds via clouds.toml.

When to use it

• Multi-session project continuity: restore full working context when an agent re-enters a project
• Multi-agent collaboration: agents and people on a team build on the same memory
• Long-term knowledge management requiring time-travel queries and provenance chains
• Sharing accumulated knowledge within a trusted team (via kaeru-cloud, optional)
• Workflows requiring auditing and non-destructive conflict resolution

Limitations and current status

• Currently a pre-1.0 alpha version; the underlying schema may change between minor versions, so exporting to markdown is recommended when notes need to be preserved.
• Retrieval is structured-first; there is currently no vector/embedding layer; Cozo supports HNSW but kaeru does not have it wired up, and vector fallback is possible future work rather than a current feature.
• Cloud multi-tenancy/per-user or per-organization isolation is a future feature; currently each cloud is a shared space scoped by project.
• Cross-project links (cross-project edges and recall) are a future feature; currently scoping by project is a deliberate design,attach Nodes are now allowed to belong to multiple projects at the same time.
• PostgreSQL backend and project onboarding brief are future plans.
• kaeru-rig is the rig framework adapter (the full curator verb set runs as rig Tools on an embedded Arc<Store>); kaeru-langchain (Python bridge) has not been started yet.
• Default vault path: Linux $XDG_DATA_HOME/kaeru，macOS ~/Library/Application Support/ai.lamantin.kaeru，Windows %LOCALAPPDATA%\ai.lamantin.kaeru, can be overridden with KAERU_VAULT_PATH . Hygiene features are enabled by default since 0.7.3, and can be disabled with KAERU_MCP_HYGIENE_ENABLE=0 ; in kaeru-rig, hygiene remains opt-in.
• Architecturally, edges carry operational semantics (derived_from supports provenance, contradicts triggers a non-destructive under_review, supersedes unidirectionally retracts the previous version); audit_event is a first-class node type, and every change writes an audit node, separate from the underlying Validity history. Retrieval achieves project scoping through junction relations, and RocksDB prefix scans provide O(log n + k).