Dokoro

🧠 dokoro

Agentic memory for coding agents — affective routing & bi-temporal facts

A multi-layer agent memory MCP server: a persistent brain for your LLM agent. Remember what you're doing, what you did, what you know, and how well each tool actually performs — across sessions, models, and projects. Claim files, leave handoffs, and resume work without guessing — works for one agent today; prevents collisions when you add another.

[](https://bypawel.github.io/dokoro/) [](LICENSE) [](https://nodejs.org) [](https://www.typescriptlang.org/) [](https://github.com/modelcontextprotocol/typescript-sdk)

> Built on the MCP TypeScript SDK. > Storage: SQLite (Drizzle ORM) · LanceDB vectors · a small file-backed workspace.

---

Why this exists

An LLM agent's context window is its only memory, and it's wiped at the end of every session. The agent re-learns the codebase, re-discovers decisions it already made, and repeats tools that failed last time. Most "memory" plugins paper over this with a single undifferentiated vector store — everything dumped in, everything retrieved by fuzzy similarity.

dokoro takes the opposite stance: memory is separated by function, following the CoALA-inspired taxonomy used by Letta, Zep, Mem0, and Cognee. Each layer answers a different question, so the agent retrieves the right kind of memory instead of the most textually similar one.

| The agent asks… | …and the right layer answers | |---|---| | "What was I doing?" | Working memory | | "What happened last time?" | Episodic memory | | "Have I seen this entity before?" | Semantic graph | | "What plan am I executing?" | Procedural memory | | "Does this tool usually work?" | Affective memory |

---

In practice — a Claude Code session

Monday. Claude Code fixes a flaky login test and logs it as it goes:

You    ▸ The concurrent-login test is flaky. Fix it.
Claude ▸ [calls dokoro_session_log] Logged: root cause = race in session refresh,
         partial fix in auth/session.ts. Open question: needs a regression test.

Thursday, fresh session, zero context. Instead of re-investigating from scratch, Claude recalls:

You    ▸ Pick up the login bug from earlier this week.
Claude ▸ [calls dokoro_session_recall { query: "login", since: "2026-05-12" }]
         Resuming from Monday's session — writing the regression test now.

Summaries are written at session end with dokoro_session_summary_add (and tool outcomes are auto-captured along the way). dokoro_session_recall then returns the matching episodic summaries — narrowed by query substring and an ISO since bound, then semantically re-ranked by embedding similarity (falling back to recency when offline) — as compact text the agent reads directly. Long sessions are auto-compacted once their summaries grow past the token budget; the consolidated summary is retained as a single recallable entry, so nothing drops out of recall:

[2026-05-19T14:32:00Z] session=2026-05-19-login model=claude-opus-4-7 msgs=42
  Fixed race in session refresh; partial fix in auth/session.ts; TODO: regression test

---

What makes it different

Most memory servers stop at "store text, retrieve by similarity." Two capabilities set dokoro apart — and both are queryable as plain MCP tool calls.

❤️ Affective memory — the agent learns which tools to trust

Every tool outcome is recorded — outcome and latency are captured automatically for wrapped tool calls; confidence is recorded when provided via an explicit dokoro_feedback_record call. The agent then asks dokoro_feedback_route for a ranked track record and biases itself accordingly — no other popular OSS memory lib (Mem0, Letta, Zep, Cognee, LangMem) does this natively.

// MCP tools/call — ranked routing scores for this agent
{
  "name": "dokoro_feedback_route",
  "arguments": { "agent_id": "claude-code", "half_life_days": 14 }
}

dokoro_session_recall:      n=89  success=89  failure=0 partial=0 rejected=0 timeout=0  decayed_rate=1.000 wilson_lower=0.9583 confident=true
dokoro_entity_extract_deep: n=142 success=125 failure=2 partial=0 rejected=0 timeout=15 decayed_rate=0.864 wilson_lower=0.8213 confident=true

> Ranking is a Wilson lower bound (so a single lucky success can't outrank a long track record) with recency decay (half_life_days, so stale failures fade) and a confident flag once a tool clears the minimum sample size. The agent prefers the higher wilson_lower — turning past outcomes into a routing policy. Raw aggregates remain available via dokoro_feedback_query.

🕒 Bi-temporal facts — query the graph "as of" any point in time

Every entity_relations row carries valid_from / valid_to (Zep/Graphiti-style), so facts are never destructively overwritten — a superseded fact has its window closed (valid_to set) and a new slice opens. Pass as_of and the graph traversal returns only the relations that were valid at that moment — point-in-time time-travel over the knowledge graph:

// MCP tools/call — what did this module relate to as of April 2026?
{
  "name": "dokoro_entity_graph",
  "arguments": { "entityId": 7, "as_of": "2026-04-01T00:00:00Z" }
}

## Entity: auth/session.ts
- **Type:** file
- **ID:** 7

### Relations (depth 2, 1 found)
- auth/session.ts --[uses]--> jwt-stateless-tokens

> Once that fact's window is closed, the default "now" view stops returning it — it only surfaces when you ask "as of" a date inside its validity window; the history is never deleted. Window-closing on supersession is active for single-valued relations (the set is empty by default — add types to FUNCTIONAL_RELATION_TYPES in entity-extractor.ts to enable it); genuinely many-valued relations like depends_on or implements accumulate concurrent open facts instead of evicting each other.

Plus: hybrid search (SQLite FTS5 + LanceDB vectors via Reciprocal Rank Fusion) and an optional local LLM (Ollama) for embeddings and deep entity extraction — the server runs fine without it, falling back to regex.

---

How an agent uses it

dokoro is an MCP server: it exposes tools, and the agent — Claude Code, Gemini CLI, or any MCP client — calls them. There is no autonomy on the server side. The server stores and serves; the agent reads and writes. A typical session forms a loop across the layers:

   ┌──────────────────────────── session ────────────────────────────┐
   │                                                                   │
   ▼                                                                   │
 1. RESUME      workspace_status · session_recall      (read working + episodic)
 2. ORIENT      entity_graph · plan_status             (read semantic + procedural)
 3. ACT         workspace_claim · session_log          (write working)
 4. REFLECT     feedback_record                        (write affective)
 5. ROUTE       feedback_route                         (read affective)  ──┐
 6. PERSIST     workspace_dump                          (write → episodic) │
   │                                                                       │
   └───────────────────────────────────────────────────────────────────◄─┘

1. Resume — dokoro_workspace_status shows whether a task is already in flight; dokoro_session_recall loads summaries of prior sessions. The agent starts informed instead of blank.
2. Orient — dokoro_entity_graph reveals the relevant files/services/decisions and how they relate; dokoro_plan_status shows which plan tasks remain.
3. Act — it claims the workspace (dokoro_workspace_claim, a file-based lock so two agents don't collide), logs progress with dokoro_session_log, records open questions with dokoro_question_add.
4. Reflect — after each significant tool call, dokoro_feedback_record captures the outcome (success / failure / latency / confidence).
5. Route — dokoro_feedback_query lets the agent bias itself toward the model or tool that has historically succeeded.
6. Persist — dokoro_workspace_dump flushes the active workspace into durable storage, ready for the next recall.

The payoff: the agent never holds all of this in its context window. It pulls the slice it needs from the layer that owns it, then writes back what it learned.

---

The five memory layers

| Layer | What it remembers | Where it lives | MCP tools | |---|---|---|---| | 🟢 Working | Current task, locks, open questions | current-workspace.md + sessions(status='active') + questions.json | dokoro_workspace_claim, dokoro_workspace_dump, dokoro_workspace_status, dokoro_session_log, dokoro_question_* | | 🔵 Episodic | Past sessions, time entries, conversation summaries | sessions, time_entries, conversation_summaries | dokoro_session_recall, dokoro_session_log | | 🟣 Semantic | Facts, entities, relations, tags, doc vectors | entities, entity_relations (bi-temporal), doc_entities, tags, doc_tags, docs, LanceDB doc_vectors + chunks | dokoro_entity_graph, dokoro_entity_extract_deep | | 🟠 Procedural | Plans, workflows, checklists | docs(doc_type='plan') + plan JSON files | dokoro_plan_create, dokoro_plan_check, dokoro_plan_validate, dokoro_plan_status, dokoro_plan_list, dokoro_plan_blocker | | 🔴 Affective | Per-tool/per-agent success, failure, latency, confidence | agent_feedback | dokoro_feedback_record, dokoro_feedback_query |

┌───────────── working ─────────────┐    ┌───────── affective ──────────┐
│  workspace.md │ sessions(active)   │    │  agent_feedback               │
└────────────────────────────────────┘    └───────────────────────────────┘
┌──── episodic ────┐  ┌────── semantic ──────┐  ┌──── procedural ────┐
│ sessions │ time_ │  │ entities │ relations │  │ docs(plan)         │
│ entries  │ conv_ │  │ doc_vectors (Lance)  │  │ plans/*.json       │
│ summaries│       │  │ tags │ doc_entities  │  │                    │
└──────────────────┘  └──────────┬───────────┘  └────────────────────┘
                                  │
                           Drizzle / SQLite

---

Tools

Tools are organised by which memory layer they read or write.

🟢 Working memory — current task

| Tool | Description | |------|-------------| | dokoro_workspace_status | Check workspace status and active sessions | | dokoro_workspace_claim | Claim workspace with a file-based lock | | dokoro_workspace_dump | Export workspace data (registers docs in SQLite) | | dokoro_session_log | Log development session entries with tags | | dokoro_regenerate_current | Auto-generate or update current.md from recent activity | | dokoro_update_current_section | Update a specific section in current.md | | dokoro_get_current_focus | Read the current focus and active tasks from current.md | | dokoro_block_write | Create/update a shared editable memory block (optimistic version lock) | | dokoro_block_read | Read a shared block (content + version + last updater) | | dokoro_block_list | List shared blocks (key, version, updater) | | dokoro_handoff_write | Record a cross-session handoff (summary + open items) | | dokoro_handoff_inbox | Read open handoffs targeted to / available to an agent | | dokoro_handoff_claim | Atomically claim a handoff so only one agent takes it | | dokoro_presence_ping | Heartbeat — announce this agent is active (status, focus) | | dokoro_presence_list | List agents currently active in the project (read-time TTL) | | dokoro_file_claim | Advisory per-file claim with a lease (default 300 s, max 3600 s) — warns other agents, never blocks | | dokoro_file_release | Release your file claims (specific paths or all:true) — owner-aware, idempotent | | dokoro_claim_list | List open file claims with holder liveness (live / stale / unknown via agent_presence) | | dokoro_question_add | Log a question during development | | dokoro_question_answer | Answer a previously logged question | | dokoro_question_list | List all tracked questions | | dokoro_question_check | Check status of open questions |

🔵 Episodic memory — past sessions

| Tool | Description | |------|-------------| | dokoro_session_recall | Read past session summaries (filter by query, session_id, since timestamp) | | dokoro_session_summary_add | Write a session-end summary — the episodic write path | | dokoro_compress_week | Generate a compressed weekly summary (sessions, tasks completed, decisions made) — analytics server only |

🟣 Semantic memory — facts and the knowledge graph

| Tool | Description | |------|-------------| | dokoro_entity_graph | Query the entity graph — search by name/type or traverse from a specific entity. Accepts as_of ISO timestamp for point-in-time queries against bi-temporal entity_relations. | | dokoro_entity_extract_deep | Run LLM-powered deep extraction on a document via Ollama (requires llama3.2) |

🟠 Procedural memory — plans and workflows

| Tool | Description | |------|-------------| | dokoro_plan_create | Create a development plan with tasks | | dokoro_plan_check | Check progress on a plan's tasks | | dokoro_plan_blocker | Report a blocker on a plan task | | dokoro_plan_validate | Validate plan completion criteria | | dokoro_plan_status | Get overall plan status summary | | dokoro_plan_list | List all plans |

🔴 Affective memory — agent feedback

| Tool | Description | |------|-------------| | dokoro_feedback_record | Record the outcome of a tool call (success / failure / partial / rejected / timeout) with confidence and latency | | dokoro_feedback_route | Ranked track record (Wilson lower bound + recency decay) to bias tool/model routing | | dokoro_feedback_query | Per-tool success rates, recent failures, agent-specific stats |

⚙️ Other — setup and assets

| Tool | Description | |------|-------------| | dokoro_init | Initialize dokoro workspace and database | | dokoro_archive_sweep | Sweep stale daily files and finished plans into the archive (dryRun to preview, status_only to inspect the last run) | | dokoro_save_image | Save an image asset (base64 or URL) | | dokoro_save_file | Save a file asset | | dokoro_list_assets | List saved assets |

> Tools above are exposed by the core server (bin/dokoro-core.js). The optional analytics server (bin/dokoro-analytics.js) adds dokoro_compress_week. Other modular servers (search, planning, tracking) expose additional tools not yet wired into core — see src/servers/*.ts.

---

Multi-agent file claims

When several agents share one worktree, dokoro_file_claim gives them an advisory per-file ledger: claim the files you're about to edit, and everyone else sees who is editing what. Claims warn — they never block:

• Lease semantics — a claim expires after ttl_seconds (default 300 s, max 3600 s); renew by re-claiming the same path (bumps a monotonic heartbeat_seq and extends the lease).
• All-or-nothing — claiming multiple paths either acquires every one or none; a conflict returns a per-path report with the live holder's agent_id, intent, expiry, and presence.
• Stale takeover — an expired claim, or one whose holder's agent_presence heartbeat is stale (> 900 s), is taken over automatically; force:true overrides even a live holder (recorded as a forced takeover).
• One clock — all timestamps are server-assigned SQLite unixepoch seconds, so agents on different machines can't disagree about expiry.

dokoro_claim_list shows open claims with holder liveness (live / stale / unknown); dokoro_file_release releases your own claims (and only yours). Backed by the file_claims table (migration v12).

---

Automatic archiving

The workspace stays tidy without manual housekeeping:

• Validated plans — dokoro_plan_validate auto-archives a va

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: byPawel
• Source: byPawel/dokoro
• License: MIT
• Homepage: https://bypawel.github.io/dokoro/

Install and usage instructions live in the source repository linked above.