<div align="center">

🧠 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.

</div>

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 (FUNCTIONAL_RELATION_TYPES in entity-extractor.ts is ['superseded_by'] by default, so a newer successor closes the prior open window — add more types there to extend 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.

<details open> <summary><strong>🟢 Working memory</strong> — current task</summary>

| 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 —