An agent that remembers.
dokoro is a persistent brain for your LLM agent — five memory layers, each answering a different question, so the agent recalls the right kind of memory instead of the most textually similar one.
Working · episodic · semantic · procedural · affective — with bi-temporal facts, a track record of which tools to trust, and file claims and handoffs so a second agent never collides with the first.
- 5
- Memory layers
- 3
- Storage backends
- 44
- MCP tools
- MIT
- License
SQLite + LanceDB · built on the MCP TypeScript SDK · Node ≥ 22. Tool count includes the analytics tool and three opt-in bridge tools.
Install per project.
On npm as dokoro. One command — no clone, no build. Run it from the project directory: each project gets its own isolated memory in ./dokoro (override with DOKORO_PATH), so sessions, entities and tool-trust never leak between repos.
1# add dokoro to the current project (Claude Code, or any MCP client)2claude mcp add dokoro -- npx -y dokoro3 4# CLI subcommands5npx dokoro init # scaffold the dokoro workspace6npx dokoro migrate # run DB migrations7npx dokoro browse # interactive memory browser (TUI)8 9# lean install — skip the ~100MB native vector deps (lazy-loaded)10npm install --omit=optional1# optional — embeddings + deep entity extraction2ollama pull nomic-embed-text3ollama pull llama3.24ollama serve- Claude Codeclaude mcp add …
- Gemini CLIMCP over stdio
- Cursor · Continue · ClineMCP extension or settings entry
- Any MCP clientJSON-RPC 2.0 over stdio
Building from source or pinning a local checkout? See the README quick start ↗
Memory, separated by function.
Most memory plugins dump everything into one vector store. dokoro follows the CoALA taxonomy used by Letta, Zep and Mem0 — each layer owns a question, a storage home, its own tools, and its own retention span.
The scratchpad for the task in hand — plus a file-lock so two agents don't trample each other. Like RAM: fast, current, cleared when the task ends.
A dated diary of past sessions, written at session end and auto-compacted as it grows. A fresh session resumes days later instead of re-investigating.
The knowledge graph: entities (files, services, decisions), how they relate, plus document vectors. Answers by meaning, not text match — every relation is bi-temporal.
The plans and checklists the agent is working through, with progress and blockers. “Where am I in the plan” survives the context window.
A per-tool, per-agent track record — success, failure, latency, confidence. Wilson-ranked and recency-decayed into a routing policy.
The session loop.
The server stores and serves; the agent reads and writes. A session forms a loop across the layers — resume informed, act, reflect, and persist what was learned for next time.
- 01Resumeworkspace_status · session_recallread working + episodic — start informed, not blank
- 02Oriententity_graph · plan_statusread semantic + procedural — what's relevant, what's left
- 03Actworkspace_claim · session_log · question_addwrite working — claim, log progress, record questions
- 04Reflectfeedback_recordwrite affective — capture each tool outcome
- 05Routefeedback_routeread affective — bias toward what historically worked
- 06Persistworkspace_dumpwrite → episodic — ready for the next recall
Monday's fix, recalled on Thursday.
Summaries are written at session end with dokoro_session_summary_add. dokoro_session_recall narrows by query and an ISO since, then re-ranks by embedding similarity — falling back to recency offline. Long sessions are auto-compacted into one recallable entry, so nothing drops out of recall.
How agent memory evolved.
From no memory at all, to one similarity bucket, to tiered OS-like memory, to temporal graphs. dokoro sits at the current edge.
Affective memory — learning what to trust.
Every tool outcome is recorded — outcome and latency automatically for wrapped calls, confidence when provided via dokoro_feedback_record. The agent asks dokoro_feedback_route for a ranked track record and biases itself accordingly. None of Mem0, Letta, Zep, Cognee or LangMem does this natively.
1{2 "name": "dokoro_feedback_route",3 "arguments": {4 "agent_id": "claude-code",5 "half_life_days": 146 }7}dokoro_session_recall n=89 decayed_rate=1.000 wilson_lower=0.9583 confident=true dokoro_entity_extract_deep n=142 success=125 timeout=15 decayed_rate=0.864 wilson_lower=0.8213 confident=true
- tool call→
- outcomeok · fail · latency→
- agent_feedbackSQLite row→
- recency decayhalf_life_days→
- wilson boundlower-bound rank→
- route
Bi-temporal facts.
Every entity_relations row carries valid_from / valid_to (Zep / Graphiti-style). Facts are never overwritten — a superseded fact has its window closed and a new slice opens. Drag as_of to query the graph at any point in time.
1{2 "name": "dokoro_entity_graph",3 "arguments": {4 "entityId": 7,5 "as_of": "2026-04-01T00:00:00Z"6 }7}Pass as_of and traversal returns only relations valid at that moment. A closed fact stops surfacing in the default “now” view — but history is never deleted.
Window-closing on supersession applies to single-valued relations (FUNCTIONAL_RELATION_TYPES, superseded_by by default). Many-valued relations like depends_on or implements accumulate concurrent open facts instead of evicting each other.
Three backends, each to its strength.
Structured data in SQLite, vectors in LanceDB, human-readable state on the filesystem. Hybrid search fuses FTS5 + vectors by Reciprocal Rank Fusion. Ollama is optional — without it, dokoro falls back gracefully.
- docs · entities · entity_relations
- sessions · time_entries
- tags · doc_tags · doc_entities
- conversation_summaries
- agent_feedback (affective)
- FTS5 full-text index
- doc_vectors + chunks
- 512-token windows, 128 overlap
- nomic-embed-text embeddings
- cosine similarity recall
- RRF-fused with FTS5
- current-workspace.md
- daily/*.md session logs
- plans/*.json (procedural)
- questions.json
- assets/* · lock.json
- nomic-embed-text → embeddings
- llama3.2 → deep extraction
- without it: regex extraction
- incremental SHA-256 indexing
Claims, handoffs, presence.
Works for one agent today; prevents collisions when you add another. Every timestamp is a server-assigned SQLite unixepoch, so agents on different machines never disagree about expiry.
Per-file leases (default 300s, max 3600s); renew by re-claiming. Claims warn — they never block.
Claiming several paths acquires every one or none; conflicts name the live holder, intent, expiry and presence.
An expired claim, or one whose holder's heartbeat is stale, is taken over automatically. force:true is recorded as a forced takeover.
Editable blocks with optimistic version compare-and-set, and handoffs that exactly one agent can atomically claim.
Automatic archiving.
- Validated plans are archived by
dokoro_plan_validate— still listed, marked (archived), read-only. - Opportunistic sweep on workspace claim: daily files older than 7 days and finished plans older than 30 days move to the archive — never the current week, never a claimed file.
- On demand with
dokoro_archive_sweep—dryRunto preview,status_onlyfor the last run.
Supervise agents live.
npx dokoro browse is a terminal dashboard over the whole memory folder — ten categories, from the live workspace and plans to file claims, agent presence, open questions and the feedback ledger. File watchers keep lists live; changed lines flash as agents work.
Read everywhere, write only where gated. Command palettes, multi-select and inline editing were rejected — a coordination dashboard must never race the agents it watches.
Releases a stuck claim only when the holder's heartbeat is stale past the 900s TTL or the lease expired. A live holder is refused — the TUI has no force path.
Advances a plan one legal step (draft → active → completed). The plan is re-read before writing; if its status drifted since you confirmed, the write aborts.
Every write is armed by one key, confirmed y/n, re-read, then gated. It either lands race-guarded in SQL or is refused with a toast.
Not a TTY (pipes, CI)? It prints a static category summary instead.
Every tool, by layer.
44 tools, grouped by the memory layer they read or write. Core tools ship on the core server; dokoro_compress_week lives on the analytics server and the bridge tools are opt-in.
Workingworkspace · shared blocks · handoffs · presence · file claims · questions22+
dokoro_workspace_statusCheck workspace status and active sessions.dokoro_workspace_claimClaim the workspace with a file-based lock so two agents don't collide.dokoro_workspace_dumpFlush the active workspace into durable storage; registers docs in SQLite.dokoro_session_logLog development session entries with tags as work happens.dokoro_regenerate_currentAuto-generate or refresh current.md from recent activity.dokoro_update_current_sectionUpdate a specific section of current.md.dokoro_get_current_focusRead the current focus and active tasks from current.md.dokoro_block_writeCreate/update a shared editable block; optimistic version compare-and-set.dokoro_block_readRead a shared block: content, version, last updater.dokoro_block_listList shared blocks with version + updater.dokoro_handoff_writeRecord a cross-session handoff: summary + open items.dokoro_handoff_inboxRead open handoffs available to an agent.dokoro_handoff_claimAtomically claim a handoff so only one agent takes it.dokoro_presence_pingHeartbeat: announce this agent is active (upsert, server clock).dokoro_presence_listList agents live within the TTL (read-time liveness, no sweeper).dokoro_file_claimAdvisory per-file claim with a lease (default 300s) — warns, never blocks.dokoro_file_releaseRelease your file claims — specific paths or all. Owner-aware, idempotent.dokoro_claim_listList open file claims with holder liveness (live / stale / unknown).dokoro_question_addRecord an open question during development.dokoro_question_answerAnswer a previously logged question.dokoro_question_listList all tracked questions.dokoro_question_checkCheck the status of open questions.
Episodicsession recall and summaries3+
dokoro_session_recallRead past session summaries — filter by query, session_id, since; semantically re-ranked.dokoro_session_summary_addWrite a session-end summary; auto-compacted past the token budget.dokoro_compress_weekCompressed weekly summary — sessions, tasks, decisions (analytics server).
Semanticentity graph and deep extraction2+
dokoro_entity_graphSearch or traverse the entity graph. Accepts as_of for point-in-time queries.dokoro_entity_extract_deepLLM-powered deep extraction on a document via Ollama (llama3.2).
Proceduralplans and checklists6+
dokoro_plan_createCreate a development plan with tasks.dokoro_plan_checkCheck progress on a plan's tasks.dokoro_plan_blockerReport a blocker on a plan task.dokoro_plan_validateValidate plan completion criteria (auto-archives the plan).dokoro_plan_statusGet an overall plan status summary.dokoro_plan_listList all plans, archived ones included.
Affectivetool-outcome ledger and routing3+
dokoro_feedback_recordRecord a tool-call outcome (success / failure / partial / rejected / timeout) with confidence + latency.dokoro_feedback_routeRanked track record — Wilson lower bound + recency decay.dokoro_feedback_queryRaw per-tool success rates, recent failures, agent-specific stats.
Setupinit · archive · assets5+
dokoro_initInitialize the dokoro workspace and database.dokoro_archive_sweepSweep stale daily files and finished plans into the archive (dryRun, status_only).dokoro_save_imageSave an image asset (base64 or URL).dokoro_save_fileSave a file asset.dokoro_list_assetsList saved assets.
Bridgeopt-in · DOKORO_ENABLE_TACHIBOT_BRIDGE=true3+
bridge_index_researchIndex tachibot research output into LanceDB. Deterministic IDs — no duplicates.bridge_import_planImport planner_maker phases into dokoro plans (plan_check / _validate / _status).bridge_get_contextPull prior research + plans as a paste-ready context block for the next reasoning call.
Parameters and return shapes: docs/tools.md ↗ · README tool tables ↗
How it compares.
Four capabilities set dokoro apart — bi-temporal facts, per-agent affective feedback, multi-agent coordination and WAL concurrency — all queryable as plain MCP tool calls or visible in the SQLite schema.
| Project | Architecture | Native temporal | Native affective | Native multi-agent | Concurrent access |
|---|---|---|---|---|---|
| dokoro | SQLite + LanceDB + entity graph | ✓ bi-temporal | ✓ agent_feedback | ✓ shared blocks + handoff + file claims | ✓ WAL + busy_timeout=5000 |
| Mem0 | Vector + optional graph | — | — | — | — |
| Letta (MemGPT) | Tiered, OS-like, self-editing | ◐ via metadata | ◐ via metadata | ◐ shared blocks | — |
| Zep / Graphiti | Temporal knowledge graph | ✓ bi-temporal | — | — | — |
| Cognee | Graph + vector poly-store | ◐ partial | — | — | — |
| LangMem | Modular over LangGraph | — | — | — | — |
How it holds together.
The agent never holds it all in context — it pulls the slice it needs from the layer that owns it, then writes back what it learned.
Full system diagram, data flow and storage notes: docs/architecture.md ↗ · Animated walkthroughs: bypawel.github.io/dokoro ↗
TachiBot thinks. dokoro remembers.
Multi-model calls are stateless — research and plans evaporate when the turn ends. Three opt-in bridge tools (DOKORO_ENABLE_TACHIBOT_BRIDGE=true) land each model's output in the right layer and feed it back into the next decision.
| Bridge tool | Direction | What it does |
|---|---|---|
| bridge_index_research | tachibot → semantic | Indexes research output into LanceDB. Re-indexing the same source + query replaces the old entry. |
| bridge_import_plan | tachibot → procedural | Imports planner_maker phases into dokoro plans, usable by plan_check / _validate / _status. |
| bridge_get_context | dokoro → tachibot | Pulls relevant prior research + plans as a paste-ready context block for the next reasoning call. |