LamantinAI/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 — each project a constellation of stars around its core, sized by memory layer, with ochre cross-project bridges, reasoning-chain replay, and a time-lapse of how the knowledge grew. Hover a node to trace its neighbours; click to pin them.
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 ~70 primitives (awake, recall, drill, claim, synthesise, at, history, settle, …) 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. settle 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 set by memory layer (Core → Hot → Warm) and surfaces the archival **cortex** (settled knowledge) alongside it, so durable facts re-enter every session; surface reaches the archived Cold / Frozen on demand.
- **Reasoning chains** — chain saves the load-bearing weighted path between two nodes as a recallable trail with an agent-authored summary; why reads a trail — give it a chain for its ordered steps, or any node to reach the chain it belongs to. Duplicates are folded at creation, and rechain refreshes a trail after the graph changes (re-links, re-weights).
- **Self-maintenance** — reflect computes a tidy-up work-list: orphan nodes to link, overdue tasks, chains gone stale, settled work to promote into cortex, and shared/cloud items whose rebalancing is escalated to the user. The agent calls it at the end of a piece of work; layer tidying runs on its own in the background (hygiene).
- **Role slots** — slot gives an initiative a role held by exactly one live node (handoff, entrypoint, queue). Filling it archives the previous holder to Cold and links supersedes from the new holder to it, so a project cannot drift into three "current" handoffs. Nothing is deleted; the predecessor stays reachable through at / surface.