@loicngr/kobo 2.1.7 → 2.1.10

package/AGENTS.md

@@ -127,6 +127,11 @@ src/
 | `schema_migrations` | applied migration versions, names and timestamps |
 | `workspace_chat_history` | chat-input history per workspace: message text + `created_at`, ordered by autoincrement id, capped at 200 entries by the service; CASCADE DELETE on workspace |
 | `workspace_permission_rules` | remembered per-workspace tool approvals, scoped to an exact operation or every invocation of a tool; CASCADE DELETE on workspace |
+| `memory_scopes` / `memory_entries` | global, normalized-project and workspace scopes; active explicit facts with revision and provenance |
+| `memory_proposals` | pending Hybrid project/global writes; body retained only while pending and removed on approval/rejection/clear |
+| `memory_operations` | paginated content-free mutation/read journal with actor, source and affected-count metadata |
+| `memory_contexts` | per-launch receipts with dispatch state, revision refs, omissions and budget metadata; CASCADE DELETE on workspace/session |
+| `memory_budget_contexts` | cumulative native conversation/epoch and external cooperative-context ledgers, including delivered refs and conservative charges |
 
 `status` enum: `created | extracting | brainstorming | executing | compacting | awaiting-user | completed | idle | error | quota`. Transitions are validated in `updateWorkspaceStatus` against `VALID_TRANSITIONS`.
 
@@ -140,6 +145,16 @@ src/
 
 Tasks have `role` (`work | finalization`) and structured `verification`. MCP and HTTP share transactional task mutations. An auto-loop task cannot become done without passing reported checks. Finalization runs after all other tasks/criteria, is invalidated by scope changes, and is mandatory before completion. The proof is agent-reported evidence, not server-side execution of arbitrary commands.
 
+## Persistent memory
+
+Kōbō memory is independent of provider chat history/native memory and shared by Claude Code and Codex. `memoryMode` is a global setting defaulting to `hybrid`: Manual permits reads only; Hybrid applies workspace writes and proposes project/global writes; Automatic applies writes to the explicitly targeted scope. Mode is checked per operation, so a setting change affects existing agent sessions; pending/rejected proposals are never automatically approved or revived. Plan/review/report-only capabilities cannot write.
+
+`memory_scopes` identify global, normalized configured project path, or durable workspace id. Project identity is not a display name, branch, or worktree path. Clear is transactional: it deletes entries and pending proposals only from the exact scope, increments generation, and writes content-free journal metadata. Every delayed writer supplies its expected generation. Workspace archive/purge preserves memory; workspace deletion cascades its own scope and launch records while leaving global/project scopes intact. Provenance FKs become null when the source session/workspace is deleted; saved memory remains in its scope until explicitly erased.
+
+Agents deliberately save knowledge through shared internal MCP tools; there is no background transcript extraction or extra LLM turn. Workspace-bound tool calls derive actor, scope and write permission from a per-launch capability. It is revoked when stopping begins; bodies cannot forge human identity or widen workspace scope. External clients use the same service through `/api/mcp` HTTP or global stdio, explicitly select scopes, and receive `external-mcp` provenance (display name + transport). They need no native session. They cannot delete, approve, promote or bulk-clear memory.
+
+Context injection and every memory-tool response are bounded independently of provider window telemetry. Bootstrap targets 1,000 estimated tokens; normal responses target 1,000 with a hard 1,500-token cap; cumulative native conversation/context epoch retrieval output is capped at 6,000 estimated tokens. Retrieval output stops at 5,500 to preserve a single 500-token terminal denial reserve; later exhausted MCP reads return `isError: true` and empty `content`. Final serialized envelopes are guarded by a 12,000-byte ceiling and 96-byte framing headroom, including escaped and structured MCP duplication. These conservative estimates are not full conversation occupancy. Scope catalogues include generation/revision for CAS writes. Listing/search defaults to compact metadata and explicit body fragments are charged by range; repeated unchanged content is not blindly resent on resume. A confirmed current-controller compaction opens a new budget epoch. Failed/ambiguous delivery is charged conservatively and never replayed automatically. External stateless callers should reuse opaque external `memory_context_id`; it is not authentication and never addresses an internal ledger. See `src/shared/memory-tools.ts`, `services/memory-context-service.ts`, `services/memory-budget-service.ts`, and [CONFIGURATION.md](./CONFIGURATION.md#persistent-memory). Saving (`remember`) and scope discovery (`list_memory_scopes`) are independent of this retrieval budget, including in already-exhausted sessions. Their body-free control replies/errors stay capped at 1,000 estimated tokens per call, with `budget.chargedTokens: 0`; they neither charge nor reset the retrieval ledger. Repeated control replies still occupy model context and must not be polled. Existing permissions, mode and CAS checks remain mandatory.
+
 `auto_loop_messages` durably queues next-iteration instructions, independently of engine session ids. A dispatch interrupted before confirmed completion becomes `unknown`, requiring explicit acknowledgement or retry. Unknown or in-flight instructions prevent completion. Actual engine closure (`EngineProcess.closed`), not a logical end event alone, releases controller ownership and permits the next writer.
 
 `brainstorm_model` (nullable, set only at creation) lets a workspace created with `auto_loop=1` run its initial brainstorming session on a different model than the auto-loop iterations that follow, while staying on the same engine. `POST /api/workspaces` uses it for the very first `startAgent` call only; every subsequent auto-loop iteration (`auto-loop-service.ts`'s `spawnNextIteration`) always reads `model`, unchanged. The switch to `model` takes effect once that first live session ends naturally — not at the `[BRAINSTORM_COMPLETE]` marker, since the same session keeps running under `brainstorm_model` until it stops on its own.
@@ -177,10 +192,13 @@ Every feature that touches the schema:
 
 - **Run migrations on every backend start.** `src/server/index.ts` opens the connection with `getDb()`, checks for pending migrations, attempts a pre-migration backup, then calls `runMigrations(db)`. `getDb()` only opens/configures SQLite; it does not initialize or migrate the schema. Tests creating their own database must initialize it explicitly.
 - **Settings migrations are separate.** The JSON settings migration versions in `settings-service.ts` are independent of SQLite's `SCHEMA_VERSION`.
+- **Memory is migration v51** (`persistent-memory-schema`). Keep `initMemorySchema` in `src/server/db/memory-schema.ts` synchronized with fresh-install schema. `memoryMode` is a JSON setting and defaults to Hybrid for missing/invalid legacy values; it is not a SQLite column.
 - **Test upgrades, not just fresh installs.** The `migrations.test.ts` suite must exercise "old DB → new DB" paths.
 
 ## WebSocket protocol
 
+Claude SDK `task_*` messages cover agents **and** background jobs. Preserve `task_type` by task/tool identity across progress and terminal messages, which often omit it. The existing `subagent:progress` envelope also carries this lifecycle metadata for compatibility; `local_bash`, `local_workflow` and `mcp_task` must be excluded from agent cards, busy-agent counts, chat agent-name resolution and the selective stop-subagents action. Keep tracking these jobs for engine liveness and whole-session interruption. Legacy/unknown classifications and Codex agents remain supported; never classify from a description or from the agent's last tool (`Bash` can be a real agent's current action).
+
 ### External MCP dialogue and update checks
 
 `POST /api/mcp` exposes stateless Streamable HTTP discovery/dialogue tools, behind the existing Host/Origin and network-token gates. The global stdio server forwards dialogue calls through this backend so agent runtime ownership remains centralized. `workspace-message-service.ts` shares delivery with WebSocket chat.

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to Kōbō are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/). Each release is an `## <version>`
 section — the in-app "What's new" dialog reads this file.
 
+## 2.1.10
+
+- fix: correct memory budgets and subagent detection
+
+## 2.1.9
+
+- fix: resolve secret scan false positive in memory fixture
+
+## 2.1.8
+
+- feat: add persistent scoped memory with MCP access and management UI
+- fix: group subagent activity by task
+
 ## 2.1.7
 
 - feat: improve workspace agent visibility

package/CONFIGURATION.md

@@ -23,6 +23,7 @@ Reference for Kōbō configuration and external integrations. The tables cover t
 - [Network access](#network-access)
   - [Reachable addresses](#reachable-addresses)
 - [External LLM access through MCP](#external-llm-access-through-mcp)
+- [Persistent memory](#persistent-memory)
 - [Kōbō update checks](#kōbō-update-checks)
 - [Docker deployment](#docker-deployment)
   - [Choosing a compose file](#choosing-a-compose-file)
@@ -134,7 +135,7 @@ settings exports.
 | Key | Type | Purpose |
 |---|---|---|
 | `defaultModel` | `string` | Fallback model when no engine-specific default is set. |
-| `defaultModelByEngine` | `Record<engine, string>` | Per-engine default model (`claude-code` / `codex`). Fresh installs use `auto` for both engines: the runtime chooses its default model. Historical migrations and existing user choices are preserved. The actual model is reported by the engine when the session starts; an Auto configuration label is not a model name. |
+| `defaultModelByEngine` | `Record<engine, string>` | Per-engine default model (`claude-code` / `codex`). Fresh installs use Sonnet 5.5 (`claude-sonnet-5-5`) for Claude Code and `auto` for Codex. Historical migrations and existing user choices are preserved. The actual model is reported by the engine when the session starts; an Auto configuration label is not a model name. |
 | `workflowPolicy` | `{ commit, push, publish }` | Independent `manual` / `automatic` preferences, snapshotted at workspace creation. Fresh defaults are manual. See [Git preferences](#first-run-defaults-and-git-workflow-preferences). |
 | `skillSuite` | `string` | Standard, an external suite/combination, or custom instructions. Fresh default `standard`; see [Skill suites](#skill-suites). |
 | `defaultPermissionModeByEngine` | `Record<engine, mode>` | Default permission mode per engine. See [Permission modes](#permission-modes). |
@@ -804,6 +805,48 @@ The **External LLM access (MCP)** panel within global Network access settings pr
 
 External senders can supply `idempotency_key` once per intended message and reuse it on retries. The durable receipt survives backend restarts and event retention. An uncertain delivery is explicitly reported and never automatically sent again; see the MCP guide for response codes and limitations.
 
+## Persistent memory
+
+Kōbō stores deliberate, concise facts in SQLite, independently of Claude Code's native memory and provider chat history. Claude Code and Codex read the same Kōbō scopes, so a fact saved in one engine can be available to the other. There is no background transcript extractor or extra LLM call: agents must deliberately use the memory tools to save useful knowledge.
+
+Choose the global behavior in **Settings → Memory**. New and upgraded installations default to **Hybrid**:
+
+| Mode | Agent reads | Agent writes |
+|---|---|---|
+| Manual | Reads applicable notes | No writes or proposals |
+| Hybrid | Reads applicable notes | Applies workspace notes; proposes project/global changes for human review |
+| Automatic | Reads applicable notes | Applies changes to the explicitly selected scope |
+
+The setting is global, and is checked on every operation; changing it does not delete data, approve pending proposals, or revive rejected proposals. Read-only review and handoff-report launches cannot write even in Automatic mode. Human CRUD, proposal decisions, promotion and clear remain explicit actions.
+
+Memory is isolated at three levels:
+
+- **Global**: available to all workspaces.
+- **Project**: shared by workspaces using the same normalized configured repository path (not branch, display name or worktree path).
+- **Workspace**: available across that workspace's sessions and retained through archive/worktree purge.
+
+Settings can browse and clear each stored scope independently. The workspace drawer shows applicable entries, current-session delivery records, pending proposals and the operation journal; its clear action only clears that workspace scope. Clear removes active entries and proposals in that exact scope, increments its generation, and prevents delayed writes carrying the previous generation. Deleting a workspace deletes its workspace scope and launch records but retains global/project memory; project scopes remain selectable even if no workspace currently uses that path. The journal keeps bounded action/provenance metadata, not deleted note bodies. Clearing memory cannot retract text already sent to an agent or erase provider conversation history.
+
+Hybrid changes to project/global memory are proposals until a human approves them. Approval uses revision/generation checks; stale proposals remain reviewable and cannot silently overwrite concurrent edits. Promotion copies a note to a wider scope and preserves the source; conflicts are surfaced rather than overwritten. Changing modes never auto-approves pending proposals.
+
+### Bounded context and retrieval
+
+The workspace creation prompt explicitly introduces the memory tools and their scope/mode restrictions. Unchanged resumes send neither repeated guidance nor an empty memory section and consume no bootstrap budget. Content-free fingerprints track guidance and scope/revision changes; a mode/permission change refreshes guidance, and confirmed compaction opens a new epoch. A new user message alone does **not** reset the budget. Previously consumed budget is not refunded. Empty tool errors receive a UI-only explanation without adding repeated text to the model's context.
+
+At launch, Kōbō adds a compact ranked index/excerpt within a **1,000 estimated-token** bootstrap target. Individual memory tool responses target **1,000 estimated tokens**, hard-cap at **1,500**, and a native conversation/context epoch has a **6,000 estimated-token** cumulative retrieval-output ceiling. These are conservative memory budgets, not provider context-window sizes or a measurement of total conversation occupancy. Serialized output—including JSON escaping, structured MCP content and framing—is also guarded by byte limits.
+
+Saving is independent of retrieval: `remember` and `list_memory_scopes` remain available even in an existing conversation whose retrieval budget is exhausted. Their responses contain only compact receipts/scope metadata, never saved bodies, are capped at 1,000 estimated tokens per call, and report `budget.chargedTokens: 0`. They do not spend or reset the retrieval ledger. This also applies to their validation errors and to external MCP. Manual/read-only restrictions, Hybrid proposals, scope permissions, revocation and revision/generation checks still apply. These control replies are **not** covered by the cumulative retrieval ceiling; repeated calls still add small messages to the model context, so agents should not poll or repeat unchanged writes.
+
+The index may omit entries; it reports omission counts and agents can retrieve relevant notes with bounded search/read tools. Large note bodies use explicit character-range fragments and stable cursors. Listing/search returns compact metadata for unchanged entries; explicit full reads/fragments consume budget. Resume does not blindly resend unchanged notes: only new/changed material and a compact reminder may be added within the remaining allowance. A confirmed compaction starts a new memory epoch. Unknown or failed dispatches are charged conservatively; Kōbō does not automatically replay them.
+
+The native conversation ledger allows up to **5,500 tokens of regular retrieval output** and retains a **500-token terminal-receipt reserve**, for a hard **6,000-token cumulative retrieval** ceiling. One bounded exhaustion/denial response may use that reserve; later exhausted MCP reads return `isError: true` with an empty `content` array instead of repeating a free error indefinitely. Internal `/api/memory/agent` callers receive a small suppression marker so the workspace bridge can emit the same empty MCP error response. Each final serialized envelope also has a separate **12,000-byte hard ceiling** and includes **96 bytes of framing headroom** in its charge.
+
+An external MCP client uses the same memory tools and current database via `/api/mcp` HTTP or the global stdio server. `list_memory_scopes` returns each selectable scope's ID, level, generation and revision; use the current generation in `remember` and rediscover after a clear/conflict. External clients choose their target explicitly and do not need a bound workspace or native engine session. In Manual mode external writes are denied; Hybrid applies workspace writes and proposes broader changes; Automatic applies the requested scope. External provenance records a display client name and HTTP/stdio transport, not an authenticated identity. No delete, approve or clear tool is exposed to MCP clients.
+
+Because `/api/mcp` is stateless, an external client should reuse the opaque `memory_context_id` returned by memory calls to carry its cumulative retrieval allowance across tool calls. External retrieval responses share the 5,500-token allowance and a single bounded 500-token denial reserve; after the one terminal denial, later reads return `isError: true` and empty `content`. Scope discovery and saving remain available with bounded control replies. The handle is budget bookkeeping, not authentication; it cannot reference an internal native-conversation ledger. Kōbō cannot observe an external model's full context or compaction, so it cannot infer that a new ID means an empty LLM context. Keep the same ID for one external conversation and start a new one only when appropriate. Mutation calls are not retried automatically; after an uncertain result, inspect the receipt/state before deciding whether to retry.
+
+The workspace-scoped MCP capability is read-only for plan/review/report launches and is revoked as soon as stopping begins. Its token limits attribution and scope within Kōbō; it is not an operating-system sandbox for an agent with broader tools. See the [MCP memory tool guide](./src/mcp-server/README.md#persistent-memory-tools) for arguments and result details.
+
 ## Kōbō update checks
 
 The backend checks the package's npm `latest` release at startup and then every **20 minutes**, even with no browser open. All connected interfaces receive the result through the existing update banner, without reloading the page. Reconnecting clients retrieve the current snapshot.

package/DESIGN.md

@@ -221,7 +221,7 @@ The old three-tab redesign description is no longer the implementation baseline.
 
 - Section membership is declared by `navItems` in `SettingsPage.vue`: General,
   Agents, Skills, Git, Prompts, Scripts, Notion, Sentry, Forge, Voice, Notifications,
-  Worktrees, Projects, prompt Templates, Workspace templates, and Export.
+  Worktrees, Memory, Projects, prompt Templates, Workspace templates, and Export.
 - Git groups workflow preferences, conventions and branch prefixes.
   Prompts keeps post-PR/MR, review, CI-fix and finalization instructions. Project overrides use
   the same Git grouping. Retry limits belong to Agents and reminders to Notifications.
@@ -234,6 +234,16 @@ The old three-tab redesign description is no longer the implementation baseline.
   and contrast; they complement browser review rather than proving every screen
   follows this guide.
 
+## Memory surfaces
+
+Memory has two entry points in the existing settings/drawer navigation, not a separate application shell:
+
+- **Settings → Memory** owns the global mode draft/save interaction and the full scope catalogue. Scope selection, CRUD, proposal review and destructive clears are explicit; clearing one scope never implies clearing its parents or children.
+- The workspace right drawer has a **Memory** tab, lazy-loaded like other heavy panels. It is keyed to the selected workspace and current conversation (activation order, with legacy timestamp fallback), not the newest-created session. It shows the memory context that was actually recorded as delivered, including state, budget, omissions, and revision-current text only. Changed/deleted facts are placeholders, never historical body snapshots.
+- The workspace panel keeps the journal and entries readable in the existing narrow/mobile drawer; long IDs, note text and provenance wrap instead of forcing a wider canvas. Archived or purged workspaces retain access to memory controls. The workspace clear affordance names only that scope and links to Settings for global/project management.
+
+The shared-memory policy is intentional: Hybrid is the default; workspace facts can be applied while project/global changes await human approval. Proposals and entries use the same compact, flat rows and subtle dividers as other operational panels. Destructive confirmation names the exact entry/scope or clear counts. Memory controls never imply deletion of provider chat history, and a scope clear cannot promise retraction from text already transmitted to an engine.
+
 ## CSS Variables
 
 The following core tokens mirror `src/client/src/css/design-tokens.scss`.

package/README.md

@@ -66,6 +66,10 @@ Kōbō's production build is an installable PWA — use your browser's **Install
 - **Observability**: a per-session timeline (duration, tools, tokens, errors) and a downloadable redacted diagnostic JSON.
 - **Optional integrations**: Notion (import missions) and Sentry (fix from issue URL), usable by both agent engines through saved connections, each independently toggled with a **Test connection** action; local voice transcription via `whisper.cpp`.
 
+### Persistent memory across engines
+
+Kōbō offers **Manual**, **Hybrid** (the default), and **Automatic** memory behavior in **Settings → Memory**. Global, project, and workspace scopes are shared by Claude Code and Codex but remain independently manageable. Hybrid applies workspace notes while asking for human approval before shared project/global changes. The workspace's right-hand **Memory** tab shows the current conversation's delivered context, pending proposals, and a provenance-aware operation journal. Memory has conservative per-response and per-conversation budgets; it cannot retract facts already transmitted into an agent or provider conversation. See the [persistent memory guide](./CONFIGURATION.md#persistent-memory) and [MCP memory tools](./src/mcp-server/README.md#persistent-memory-tools).
+
 ## Fresh sessions and LLM handoffs
 
 Long conversation getting crowded? Use **Continue in a fresh session** at the bottom of the right-hand Tools panel. **Change LLM** uses the same transfer flow and also lets you select another model within the current engine.

package/dist/mcp-server/kobo-tasks-server.js

@@ -3,8 +3,10 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { getDb } from '../server/db/index.js';
+import { EXTERNAL_MEMORY_TOOL_DEFINITIONS, isMemoryToolName, MEMORY_TOOL_DEFINITIONS } from '../shared/memory-tools.js';
 import { WORKSPACE_DIALOGUE_TOOLS } from '../shared/workspace-dialogue-tools.js';
 import { createTaskHandler, cronListHandler, deleteTaskHandler, getDevServerStatusHandler, getSessionUsageHandler, getSettingsHandler, getTicketSourcesHandler, getWorkspaceInfoHandler, listDocumentsHandler, listTasksHandler, listWorkspaceImagesHandler, listWorkspacesHandler, logThoughtHandler, markAutoLoopReadyHandler, markTaskDoneHandler, readDocumentHandler, readWorkspaceEventsCsvHandler, setWorkspaceAgentDescriptionHandler, updateTaskHandler, } from './kobo-tasks-handlers.js';
+import { callMemoryTool, isMemoryOutputSuppressed } from './memory-client.js';
 import { callWorkspaceDialogueTool } from './workspace-dialogue-client.js';
 const handoffId = process.env.KOBO_HANDOFF_ID;
 const handoffToken = process.env.KOBO_HANDOFF_TOKEN;
@@ -531,9 +533,11 @@ const WORKSPACE_SCOPED_TOOLS = [
         inputSchema: { type: 'object', properties: {}, required: [] },
         annotations: { destructiveHint: false, openWorldHint: false },
     },
+    ...MEMORY_TOOL_DEFINITIONS,
 ];
 const GLOBAL_TOOLS = [
     ...WORKSPACE_DIALOGUE_TOOLS,
+    ...EXTERNAL_MEMORY_TOOL_DEFINITIONS,
     {
         name: 'list_workspaces',
         description: 'List Kōbō workspaces with their id, title, status, tags, and creation date. Set tag to return only workspaces carrying that exact tag. Works even when the Kōbō backend server is not running (reads the database directly). Use this to discover existing workspaces before creating one or targeting one with archive_workspace/stop_workspace.',
@@ -632,7 +636,11 @@ const GLOBAL_TOOLS = [
  */
 const GLOBAL_TOOL_NAMES = new Set(GLOBAL_TOOLS.map((t) => t.name));
 function availableTools() {
-    const tools = workspaceId ? [...WORKSPACE_SCOPED_TOOLS, ...GLOBAL_TOOLS] : GLOBAL_TOOLS;
+    // A workspace process exposes the capability-bound memory tools exactly once.
+    // Unbound/global stdio exposes the external bridge variant instead.
+    const tools = workspaceId
+        ? [...WORKSPACE_SCOPED_TOOLS, ...GLOBAL_TOOLS.filter((tool) => !isMemoryToolName(tool.name))]
+        : GLOBAL_TOOLS;
     return tools.filter((tool) => handoffId && handoffToken
         ? tool.name === 'submit_session_handoff' || tool.annotations?.readOnlyHint === true
         : tool.name !== 'submit_session_handoff');
@@ -677,6 +685,30 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 report: a.report,
             }));
         }
+        if (isMemoryToolName(name)) {
+            if (!workspaceId) {
+                return await callWorkspaceDialogueTool(backendUrl, name, a, process.env.KOBO_NETWORK_TOKEN, process.env.KOBO_MCP_CLIENT_NAME ?? server.getClientVersion()?.name);
+            }
+            // Workspace-bound memory is always dispatched to its launch-scoped capability.
+            // It must never fall through to the unrestricted external/global bridge.
+            if (!process.env.KOBO_MEMORY_SESSION_TOKEN)
+                return fail('Memory tools require the current workspace launch capability.');
+            const memoryResult = await callMemoryTool({
+                backendUrl,
+                name,
+                args: a,
+                capability: process.env.KOBO_MEMORY_SESSION_TOKEN,
+                networkToken: process.env.KOBO_NETWORK_TOKEN,
+            });
+            if (isMemoryOutputSuppressed(memoryResult))
+                return { content: [], isError: true };
+            return {
+                ...ok(memoryResult),
+                ...(memoryResult && typeof memoryResult === 'object' && 'budgetExhausted' in memoryResult
+                    ? { isError: true }
+                    : {}),
+            };
+        }
         if (WORKSPACE_DIALOGUE_TOOLS.some((tool) => tool.name === name)) {
             if (workspaceId && a.workspace_id === workspaceId && name === 'send_workspace_message')
                 return fail('Use the normal conversation to communicate in your own workspace.');

package/dist/mcp-server/memory-client.js

@@ -0,0 +1,39 @@
+import { isMemoryToolName, validateMemoryToolArguments } from '../shared/memory-tools.js';
+export function isMemoryOutputSuppressed(value) {
+    return (!!value &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        'memoryOutputSuppressed' in value &&
+        value.memoryOutputSuppressed === true);
+}
+export async function callMemoryTool(input) {
+    if (!isMemoryToolName(input.name))
+        throw new TypeError('Unknown memory tool');
+    if (!input.capability)
+        throw new Error('Memory capability is unavailable for this process');
+    const args = validateMemoryToolArguments(input.name, input.args);
+    const headers = {
+        'Content-Type': 'application/json',
+        'X-Kobo-Memory-Session': input.capability,
+    };
+    if (input.networkToken)
+        headers['X-Kobo-Token'] = input.networkToken;
+    const timeoutMs = input.timeoutMs ?? 30_000;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1)
+        throw new TypeError('Memory request timeout must be positive');
+    const signal = AbortSignal.timeout(timeoutMs);
+    const response = await (input.fetcher ?? fetch)(`${input.backendUrl.replace(/\/$/, '')}/api/memory/agent/${input.name}`, { method: 'POST', headers, body: JSON.stringify(args), signal });
+    const raw = await response.text();
+    let payload;
+    try {
+        payload = raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        payload = { error: 'Backend returned invalid JSON' };
+    }
+    if (!response.ok) {
+        const detail = payload && typeof payload === 'object' && 'error' in payload ? String(payload.error) : response.statusText;
+        throw new Error(`Memory backend returned ${response.status}: ${detail}`);
+    }
+    return payload;
+}

package/dist/mcp-server/workspace-dialogue-client.js

@@ -1,10 +1,13 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { isMemoryToolName, validateMemoryToolArguments } from '../shared/memory-tools.js';
 import { validateDialogueArguments } from '../shared/workspace-dialogue-tools.js';
 import { normalizeClientName } from '../shared/workspace-message-types.js';
 /** Stateless HTTP bridge: external stdio clients never own agent runtime state. */
 export async function callWorkspaceDialogueTool(backendUrl, name, args, token, clientName) {
-    const arguments_ = validateDialogueArguments(name, args);
+    const arguments_ = isMemoryToolName(name)
+        ? validateMemoryToolArguments(name, args, true)
+        : validateDialogueArguments(name, args);
     const client = new Client({ name: 'kobo-stdio-bridge', version: '1.0.0' });
     const signal = AbortSignal.timeout(30_000);
     const transport = new StreamableHTTPClientTransport(new URL(`${backendUrl.replace(/\/$/, '')}/api/mcp`), {

package/dist/server/db/memory-schema.js

@@ -0,0 +1,185 @@
+/** Shared by fresh installs and the append-only v51 upgrade. */
+export function initMemorySchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS memory_scopes (
+      id TEXT PRIMARY KEY,
+      level TEXT NOT NULL CHECK (level IN ('global', 'project', 'workspace')),
+      project_path TEXT,
+      workspace_id TEXT REFERENCES workspaces(id) ON DELETE CASCADE,
+      generation INTEGER NOT NULL DEFAULT 0 CHECK (generation >= 0),
+      revision INTEGER NOT NULL DEFAULT 0 CHECK (revision >= 0),
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      CHECK (
+        (level = 'global' AND project_path IS NULL AND workspace_id IS NULL) OR
+        (level = 'project' AND project_path IS NOT NULL AND workspace_id IS NULL) OR
+        (level = 'workspace' AND project_path IS NULL AND workspace_id IS NOT NULL)
+      )
+    );
+
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_scopes_global
+      ON memory_scopes(level) WHERE level = 'global';
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_scopes_project
+      ON memory_scopes(project_path) WHERE level = 'project';
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_scopes_workspace
+      ON memory_scopes(workspace_id) WHERE level = 'workspace';
+    CREATE INDEX IF NOT EXISTS idx_memory_scopes_level_id
+      ON memory_scopes(level, id);
+
+    CREATE TABLE IF NOT EXISTS memory_entries (
+      id TEXT PRIMARY KEY,
+      scope_id TEXT NOT NULL REFERENCES memory_scopes(id) ON DELETE CASCADE,
+      memory_key TEXT NOT NULL,
+      title TEXT NOT NULL,
+      body TEXT NOT NULL,
+      revision INTEGER NOT NULL DEFAULT 1 CHECK (revision > 0),
+      actor_kind TEXT NOT NULL CHECK (actor_kind IN ('human', 'internal-agent', 'external-mcp')),
+      source_workspace_id TEXT REFERENCES workspaces(id) ON DELETE SET NULL,
+      source_session_id TEXT REFERENCES agent_sessions(id) ON DELETE SET NULL,
+      source_engine TEXT,
+      client_name TEXT,
+      transport TEXT CHECK (transport IS NULL OR transport IN ('http', 'stdio')),
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      UNIQUE (scope_id, memory_key),
+      CHECK (
+        (actor_kind = 'human' AND source_workspace_id IS NULL AND source_session_id IS NULL AND source_engine IS NULL AND client_name IS NULL AND transport IS NULL) OR
+        (actor_kind = 'internal-agent' AND source_engine IN ('claude-code', 'codex') AND client_name IS NULL AND transport IS NULL) OR
+        (actor_kind = 'external-mcp' AND source_workspace_id IS NULL AND source_session_id IS NULL AND source_engine IS NULL AND client_name IS NOT NULL AND transport IN ('http', 'stdio'))
+      )
+    );
+    CREATE INDEX IF NOT EXISTS idx_memory_entries_scope_id
+      ON memory_entries(scope_id, id);
+    CREATE INDEX IF NOT EXISTS idx_memory_entries_scope_updated
+      ON memory_entries(scope_id, updated_at DESC, id DESC);
+
+    CREATE TABLE IF NOT EXISTS memory_proposals (
+      id TEXT PRIMARY KEY,
+      scope_id TEXT NOT NULL REFERENCES memory_scopes(id) ON DELETE CASCADE,
+      target_entry_id TEXT REFERENCES memory_entries(id) ON DELETE CASCADE,
+      base_revision INTEGER,
+      memory_key TEXT NOT NULL,
+      title TEXT NOT NULL,
+      body TEXT NOT NULL,
+      generation INTEGER NOT NULL CHECK (generation >= 0),
+      actor_kind TEXT NOT NULL CHECK (actor_kind IN ('human', 'internal-agent', 'external-mcp')),
+      source_workspace_id TEXT REFERENCES workspaces(id) ON DELETE SET NULL,
+      source_session_id TEXT REFERENCES agent_sessions(id) ON DELETE SET NULL,
+      source_engine TEXT,
+      client_name TEXT,
+      transport TEXT CHECK (transport IS NULL OR transport IN ('http', 'stdio')),
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      CHECK ((target_entry_id IS NULL AND base_revision IS NULL) OR (target_entry_id IS NOT NULL AND base_revision IS NOT NULL)),
+      CHECK (
+        (actor_kind = 'human' AND source_workspace_id IS NULL AND source_session_id IS NULL AND source_engine IS NULL AND client_name IS NULL AND transport IS NULL) OR
+        (actor_kind = 'internal-agent' AND source_engine IN ('claude-code', 'codex') AND client_name IS NULL AND transport IS NULL) OR
+        (actor_kind = 'external-mcp' AND source_workspace_id IS NULL AND source_session_id IS NULL AND source_engine IS NULL AND client_name IS NOT NULL AND transport IN ('http', 'stdio'))
+      )
+    );
+    CREATE INDEX IF NOT EXISTS idx_memory_proposals_scope_id
+      ON memory_proposals(scope_id, id);
+    CREATE INDEX IF NOT EXISTS idx_memory_proposals_scope_created
+      ON memory_proposals(scope_id, created_at DESC, id DESC);
+    CREATE INDEX IF NOT EXISTS idx_memory_proposals_target
+      ON memory_proposals(target_entry_id) WHERE target_entry_id IS NOT NULL;
+
+    CREATE TABLE IF NOT EXISTS memory_operations (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      scope_id TEXT NOT NULL REFERENCES memory_scopes(id) ON DELETE CASCADE,
+      operation TEXT NOT NULL CHECK (operation IN ('created', 'updated', 'deleted', 'proposed', 'approved', 'rejected', 'promoted', 'cleared', 'read')),
+      actor_kind TEXT NOT NULL CHECK (actor_kind IN ('human', 'internal-agent', 'external-mcp')),
+      source_workspace_id TEXT REFERENCES workspaces(id) ON DELETE SET NULL,
+      source_session_id TEXT REFERENCES agent_sessions(id) ON DELETE SET NULL,
+      source_engine TEXT,
+      -- Preserve source project attribution when ON DELETE SET NULL clears workspace id.
+      source_project_path TEXT,
+      client_name TEXT,
+      transport TEXT CHECK (transport IS NULL OR transport IN ('http', 'stdio')),
+      entry_id TEXT,
+      proposal_id TEXT,
+      revision INTEGER,
+      affected_entries INTEGER,
+      affected_proposals INTEGER,
+      created_at TEXT NOT NULL,
+      CHECK (affected_entries IS NULL OR affected_entries >= 0),
+      CHECK (affected_proposals IS NULL OR affected_proposals >= 0),
+      CHECK (
+        (actor_kind = 'human' AND source_workspace_id IS NULL AND source_session_id IS NULL AND source_engine IS NULL AND client_name IS NULL AND transport IS NULL) OR
+        (actor_kind = 'internal-agent' AND source_engine IN ('claude-code', 'codex') AND client_name IS NULL AND transport IS NULL) OR
+        (actor_kind = 'external-mcp' AND source_workspace_id IS NULL AND source_session_id IS NULL AND source_engine IS NULL AND client_name IS NOT NULL AND transport IN ('http', 'stdio'))
+      )
+    );
+    CREATE INDEX IF NOT EXISTS idx_memory_operations_scope_id
+      ON memory_operations(scope_id, id DESC);
+    CREATE INDEX IF NOT EXISTS idx_memory_operations_source_workspace_id
+      ON memory_operations(source_workspace_id, id DESC);
+
+    CREATE TABLE IF NOT EXISTS memory_contexts (
+      id TEXT PRIMARY KEY,
+      workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+      session_id TEXT NOT NULL REFERENCES agent_sessions(id) ON DELETE CASCADE,
+      dispatch_id TEXT NOT NULL UNIQUE,
+      budget_context_id TEXT REFERENCES memory_budget_contexts(id) ON DELETE SET NULL,
+      budget_epoch INTEGER NOT NULL DEFAULT 0 CHECK (budget_epoch >= 0),
+      engine TEXT NOT NULL CHECK (engine IN ('claude-code', 'codex')),
+      state TEXT NOT NULL CHECK (state IN ('prepared', 'submitted', 'initialized', 'failed', 'unknown')),
+      entry_revisions_json TEXT NOT NULL,
+      scope_generations_json TEXT NOT NULL,
+      omitted_count INTEGER NOT NULL DEFAULT 0 CHECK (omitted_count >= 0),
+      estimated_tokens INTEGER NOT NULL DEFAULT 0 CHECK (estimated_tokens >= 0),
+      payload_bytes INTEGER NOT NULL DEFAULT 0 CHECK (payload_bytes >= 0),
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_memory_contexts_workspace_id
+      ON memory_contexts(workspace_id, id DESC);
+    CREATE INDEX IF NOT EXISTS idx_memory_contexts_session_id
+      ON memory_contexts(session_id, id DESC);
+
+    -- conversation_key is a backend-owned opaque identity, persisted with each
+    -- internal budget ledger. Reuse it for resumes; allocate a new key for a
+    -- fresh native conversation, including when the provider ID is not known.
+    CREATE TABLE IF NOT EXISTS memory_budget_contexts (
+      id TEXT PRIMARY KEY,
+      kind TEXT NOT NULL CHECK (kind IN ('internal', 'external')),
+      session_id TEXT REFERENCES agent_sessions(id) ON DELETE CASCADE,
+      engine TEXT CHECK (engine IS NULL OR engine IN ('claude-code', 'codex')),
+      conversation_key TEXT CHECK (conversation_key IS NULL OR length(trim(conversation_key)) > 0),
+      native_conversation_id TEXT,
+      external_context_id TEXT,
+      epoch INTEGER NOT NULL DEFAULT 0 CHECK (epoch >= 0),
+      cumulative_estimated_tokens INTEGER NOT NULL DEFAULT 0 CHECK (cumulative_estimated_tokens >= 0),
+      delivered_json TEXT NOT NULL DEFAULT '[]',
+      client_name TEXT,
+      transport TEXT CHECK (transport IS NULL OR transport IN ('http', 'stdio')),
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      CHECK (
+        (kind = 'internal' AND session_id IS NOT NULL AND engine IS NOT NULL AND conversation_key IS NOT NULL AND external_context_id IS NULL AND client_name IS NULL AND transport IS NULL) OR
+        (kind = 'external' AND session_id IS NULL AND engine IS NULL AND conversation_key IS NULL AND external_context_id IS NOT NULL AND client_name IS NOT NULL AND transport IN ('http', 'stdio'))
+      )
+    );
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_budget_internal_conversation_epoch
+      ON memory_budget_contexts(conversation_key, epoch) WHERE kind = 'internal';
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_budget_external_context
+      ON memory_budget_contexts(external_context_id) WHERE kind = 'external';
+    CREATE INDEX IF NOT EXISTS idx_memory_budget_session_id
+      ON memory_budget_contexts(session_id, id) WHERE session_id IS NOT NULL;
+  `);
+}
+/** Apply the current memory schema to an upgraded database, including additive v51 columns. */
+export function migrateMemorySchema(db) {
+    initMemorySchema(db);
+    const contextColumns = db.prepare('PRAGMA table_info(memory_contexts)').all();
+    if (!contextColumns.some((column) => column.name === 'budget_context_id')) {
+        db.exec('ALTER TABLE memory_contexts ADD COLUMN budget_context_id TEXT REFERENCES memory_budget_contexts(id) ON DELETE SET NULL');
+    }
+    if (!contextColumns.some((column) => column.name === 'budget_epoch')) {
+        db.exec('ALTER TABLE memory_contexts ADD COLUMN budget_epoch INTEGER NOT NULL DEFAULT 0 CHECK (budget_epoch >= 0)');
+    }
+    const columns = db.prepare('PRAGMA table_info(memory_operations)').all();
+    if (!columns.some((column) => column.name === 'source_project_path')) {
+        db.exec('ALTER TABLE memory_operations ADD COLUMN source_project_path TEXT');
+    }
+}

package/dist/server/db/migrations.js

@@ -1,5 +1,6 @@
 import { initAutoLoopSchema } from './auto-loop-schema.js';
 import { initMcpMessageSchema } from './mcp-message-schema.js';
+import { migrateMemorySchema } from './memory-schema.js';
 import { initReviewReturnSchema } from './review-return-schema.js';
 import { initSchema } from './schema.js';
 import { initSearchSchema } from './search-schema.js';
@@ -793,6 +794,11 @@ export const migrations = [
             db.exec('CREATE TABLE IF NOT EXISTS reliability_reset (id INTEGER PRIMARY KEY CHECK (id = 1), reset_at TEXT NOT NULL)');
         },
     },
+    {
+        version: 51,
+        name: 'persistent-memory-schema',
+        migrate: migrateMemorySchema,
+    },
 ];
 /** Current schema version — always equals the highest migration version. */
 export const SCHEMA_VERSION = migrations.length > 0 ? migrations[migrations.length - 1].version : 1;

package/dist/server/db/schema.js

@@ -1,5 +1,6 @@
 import { initAutoLoopSchema } from './auto-loop-schema.js';
 import { initMcpMessageSchema } from './mcp-message-schema.js';
+import { initMemorySchema } from './memory-schema.js';
 import { initReviewReturnSchema } from './review-return-schema.js';
 import { initSearchSchema } from './search-schema.js';
 import { initSessionHandoffSchema } from './session-handoff-schema.js';
@@ -236,4 +237,5 @@ export function initSchema(db) {
     initReviewReturnSchema(db);
     initAutoLoopSchema(db);
     initSessionHandoffSchema(db);
+    initMemorySchema(db);
 }

package/dist/server/index.js

@@ -21,6 +21,7 @@ import healthRouter from './routes/health.js';
 import imagesRouter from './routes/images.js';
 import integrationsRouter from './routes/integrations.js';
 import mcpRouter from './routes/mcp.js';
+import memoryRouter from './routes/memory.js';
 import { migrationRouter } from './routes/migration.js';
 import notionRouter from './routes/notion.js';
 import pullRequestsRouter from './routes/pull-requests.js';
@@ -41,6 +42,7 @@ import * as cronService from './services/cron-service.js';
 import { createDailyDbBackupIfNeeded, createPreMigrationBackup, startDailyDbBackupScheduler, } from './services/db-backup-service.js';
 import { startDevServer, stopAllDevServers, stopDevServer } from './services/dev-server-service.js';
 import { reconcileMessageRequests } from './services/mcp-message-request-service.js';
+import { reconcileMemoryContextsOnStartup } from './services/memory-context-service.js';
 import { authorizeWsUpgrade, generateToken, getLanHostnames, getLanUrls, isAllowedOrigin, isAllowedRequestHost, resolveBindHost, resolveDevClientOrigin, resolveNetworkAccessEnvOverrides, resolveProxyHostname, } from './services/network-access-service.js';
 import { startPrWatcher, stopPrWatcher } from './services/pr-watcher-service.js';
 import * as quotaBackoffService from './services/quota-backoff-service.js';
@@ -82,6 +84,7 @@ catch (err) {
 }
 runMigrations(db);
 reconcileMessageRequests(db);
+reconcileMemoryContextsOnStartup();
 startSearchIndex();
 // Event retention. OPT-IN: disabled by default, so this is a no-op until the
 // user sets a window in Settings → Worktrees. Deliberately not enabled by
@@ -153,6 +156,7 @@ app.get('/api/health', (c) => c.json({ status: 'ok', version: getPackageVersion(
 // Mount route sub-routers
 app.route('/api/workspaces', workspacesRouter);
 app.route('/api/mcp', mcpRouter);
+app.route('/api/memory', memoryRouter);
 app.route('/api/pull-requests', pullRequestsRouter);
 app.route('/api/workspaces', imagesRouter);
 app.route('/api/notion', notionRouter);

package/dist/server/routes/mcp.js

@@ -3,9 +3,12 @@ import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { Hono } from 'hono';
 import { bodyLimit } from 'hono/body-limit';
+import { EXTERNAL_MEMORY_TOOL_DEFINITIONS, isMemoryToolName } from '../../shared/memory-tools.js';
 import { EXTERNAL_MCP_TOOLS } from '../../shared/workspace-dialogue-tools.js';
 import { createMcpClientContext } from '../services/mcp-client-context.js';
+import { executeMemoryMcpTool } from '../services/memory-mcp-service.js';
 import { executeWorkspaceDialogueTool } from '../services/workspace-dialogue-service.js';
+import { prepareMemoryToolEnvelope } from '../utils/memory-token-budget.js';
 const app = new Hono();
 app.use('*', bodyLimit({ maxSize: 1024 * 1024 }));
 app.all('/', async (c) => {
@@ -14,11 +17,27 @@ app.all('/', async (c) => {
         sessionIdGenerator: undefined,
         enableJsonResponse: true,
     });
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: EXTERNAL_MCP_TOOLS }));
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [...EXTERNAL_MCP_TOOLS, ...EXTERNAL_MEMORY_TOOL_DEFINITIONS],
+    }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const isMemory = isMemoryToolName(request.params.name);
         try {
             const source = createMcpClientContext(c.req.header('X-Kobo-Client-Name'), c.req.header('X-Kobo-Client-Transport') === 'stdio' ? 'stdio' : 'http', c.req.header('X-Kobo-Client-Name-Encoding'));
-            const data = await executeWorkspaceDialogueTool(request.params.name, request.params.arguments ?? {}, source);
+            const data = isMemory
+                ? executeMemoryMcpTool(request.params.name, request.params.arguments ?? {}, source)
+                : await executeWorkspaceDialogueTool(request.params.name, request.params.arguments ?? {}, source);
+            if (isMemory) {
+                const bounded = prepareMemoryToolEnvelope(data, { targetTokens: 1_000, transport: 'external' });
+                if (bounded.data.memoryOutputSuppressed === true)
+                    return { content: [], isError: true };
+                const { __mcpError, ...publicData } = bounded.data;
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(publicData) }],
+                    structuredContent: publicData,
+                    ...(__mcpError === true || publicData.budgetExhausted === true ? { isError: true } : {}),
+                };
+            }
             const structuredContent = data && typeof data === 'object' && !Array.isArray(data) ? data : undefined;
             return {
                 content: [{ type: 'text', text: JSON.stringify(data) }],
@@ -27,6 +46,16 @@ app.all('/', async (c) => {
             };
         }
         catch (error) {
+            if (isMemory) {
+                const bounded = prepareMemoryToolEnvelope({
+                    error: error instanceof Error ? error.message : String(error),
+                }, { targetTokens: 1_000, transport: 'external' });
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: JSON.stringify(bounded.data) }],
+                    structuredContent: bounded.data,
+                };
+            }
             return {
                 isError: true,
                 content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],