recallnest 2.2.0 → 2.2.1

package/docs/api-reference.md

@@ -1,1291 +0,0 @@
-# RecallNest HTTP API Reference
-
-> HTTP API 文档：所有端点的请求/响应格式。服务默认监听 `127.0.0.1:4318`。
-
-Base URL: `http://localhost:4318`
-
-All endpoints accept and return JSON. Set `Content-Type: application/json` for POST requests.
-
-Workflow observation endpoints use a dedicated append-only store under `data/workflow-observations`. They do not write into the regular memory index or durable memory categories.
-
----
-
-## Health Check
-
-```
-GET /v1/health
-```
-
-Returns server status.
-
-**Response:**
-
-```json
-{
-  "status": "ok",
-  "version": "1.0.0",
-  "totalMemories": 1247,
-  "timestamp": "2026-03-15T10:00:00.000Z"
-}
-```
-
----
-
-## Recall (Quick Search)
-
-```
-POST /v1/recall
-```
-
-Semantic search across scoped memories. Best for quick, conversational lookups when the caller already knows the active scope or session.
-
-> 主动回忆：用关键词搜索相关记忆，返回按相关度排序的结果。默认需要显式 `scope`、`sessionId`，或环境里的默认 scope；只有 `allScopes=true` 才会跨 scope 搜索。
-
-**Request:**
-
-```json
-{
-  "query": "Docker bot debugging",
-  "scope": "project:docker-bot",
-  "limit": 5,
-  "minScore": 0.5
-}
-```
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `query` | string | yes | — | Search query (2-3 key nouns work best) |
-| `scope` | string | no | — | Explicit shared scope for the search |
-| `sessionId` | string | no | — | Session identifier used to infer `session:{id}` scope |
-| `allScopes` | boolean | no | `false` | Explicitly allow cross-scope search |
-| `limit` | number | no | 5 | Max results (1-20) |
-| `minScore` | number | no | 0 | Minimum relevance score (0-1). 0 = no filter |
-| `category` | string | no | — | Filter: `profile`, `preferences`, `entities`, `events`, `cases`, `patterns` |
-| `profile` | string | no | `"default"` | Retrieval profile: `default`, `writing`, `debug`, `fact-check` |
-
-**Response:**
-
-```json
-{
-  "results": [
-    {
-      "id": "a1b2c3d4",
-      "text": "Docker bot crash troubleshooting: check logs first with docker logs...",
-      "category": "cases",
-      "tier": "core",
-      "source": "cc",
-      "scope": "cc:a1b2c3d4",
-      "score": 0.87,
-      "date": "2026-03-04",
-      "boundary": {
-        "layer": "evidence",
-        "authority": "transcript-ingest",
-        "conflictPolicy": "append-only",
-        "originalCategory": "cases"
-      },
-      "canonicalKey": null,
-      "promotedFrom": null
-    }
-  ],
-  "query": "Docker bot debugging",
-  "profile": "default",
-  "totalMemories": 1247
-}
-```
-
----
-
-## Auto Recall (Resume + Focused Search)
-
-```
-POST /v1/auto-recall
-```
-
-Compose startup continuity context and then run a focused scoped search in one call. Best for agent frameworks that want a single "recall at task start" hook without exposing extra MCP tools.
-
-> 自动回忆：先做 `resume_context` 式的连续性恢复，再在同一 scope 下补一轮 focused search。适合 agent SDK / HTTP 集成在每次任务开始时直接调用。
-
-**Request:**
-
-```json
-{
-  "message": "RecallNest continuity",
-  "scope": "project:recallnest",
-  "limit": 3,
-  "limitPerSection": 3,
-  "includeLatestCheckpoint": true,
-  "profile": "default"
-}
-```
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `message` | string | yes | — | Raw user message or task-start query |
-| `task` | string | no | `message` | Optional broader task hint for resume composition |
-| `scope` | string | no | — | Explicit shared scope |
-| `sessionId` | string | no | — | Session identifier used to recover the latest checkpoint and infer scope |
-| `allScopes` | boolean | no | `false` | Explicitly allow cross-scope focused search |
-| `limit` | number | no | 5 | Max focused search results (1-20) |
-| `limitPerSection` | number | no | 3 | Max items per resume section (1-6) |
-| `includeLatestCheckpoint` | boolean | no | `true` | Whether to include the latest checkpoint in the resume payload |
-| `category` | string | no | — | Optional focused search category filter |
-| `profile` | string | no | `"default"` | Retrieval profile: `default`, `writing`, `debug`, `fact-check` |
-
-**Response:**
-
-```json
-{
-  "mode": "resume+search",
-  "query": "RecallNest continuity",
-  "profile": "default",
-  "resolvedScope": "project:recallnest",
-  "searchSkippedReason": null,
-  "resume": {
-    "summary": "Loaded 3 stable context item(s), 2 pattern(s), and 1 case(s). Latest checkpoint from codex-2026-03-16-001 on 2026-03-16: Implement startup continuity for fresh windows.",
-    "resolvedScope": "project:recallnest",
-    "stableContext": [
-      "Entity: RecallNest continuity revolves around three primitives."
-    ],
-    "relevantPatterns": [
-      "At task start, run search_memory before coding."
-    ],
-    "recentCases": [
-      "Case: RecallNest scope fallback cleanup"
-    ],
-    "latestCheckpoint": {
-      "sessionId": "codex-2026-03-16-001",
-      "resolvedScope": "project:recallnest",
-      "summary": "Implement startup continuity for fresh windows",
-      "updatedAt": "2026-03-16T05:00:00.000Z"
-    },
-    "generatedAt": "2026-03-16T05:10:00.000Z"
-  },
-  "results": [
-    {
-      "id": "a1b2c3d4",
-      "text": "RecallNest continuity revolves around three primitives: store_memory, checkpoint_session, resume_context.",
-      "category": "entities",
-      "scope": "project:recallnest",
-      "score": 0.91
-    }
-  ],
-  "count": 1
-}
-```
-
-If no explicit or inferred scope is available, `mode` becomes `resume-only`, `results` is empty, and `searchSkippedReason` explains why focused search was skipped.
-
----
-
-## Store
-
-```
-POST /v1/store
-```
-
-Store a new durable memory entry.
-
-> 存入长期记忆：适合 profile、preferences、entities、cases、patterns 这类跨窗口仍然有价值的信息。
-
-**Request:**
-
-```json
-{
-  "text": "User prefers code changes to be committed and pushed immediately",
-  "category": "preferences",
-  "source": "agent",
-  "tags": ["workflow", "git"],
-  "importance": 0.85
-}
-```
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `text` | string | yes | — | Memory content |
-| `category` | string | no | `"events"` | One of: `profile`, `preferences`, `entities`, `events`, `cases`, `patterns` |
-| `source` | string | no | `"manual"` | One of: `manual`, `agent`, `api` |
-| `scope` | string | yes | — | Required explicit scope such as `project:recallnest` or `session:abc123` |
-| `importance` | number | no | 0.7 | Importance score (0-1), affects decay and ranking |
-| `tags` | string[] | no | `[]` | Optional tags, max 8 items |
-| `canonicalKey` | string | no | derived from content | Optional stable key for dedupe/update semantics |
-
-**Response:**
-
-```json
-{
-  "id": "e5f6g7h8-...",
-  "stored": true,
-  "disposition": "stored",
-  "storedAt": "2026-03-16T02:10:00.000Z",
-  "category": "preferences",
-  "scope": "memory:agent",
-  "canonicalKey": "preferences:user-prefers-code-changes-to-be-committed-and-pushed-immediately"
-}
-```
-
-If the same `canonicalKey` is already occupied by a different durable category, RecallNest returns `disposition = "conflict"` plus a `conflictId` instead of silently creating a second durable owner.
-
-For slot-aware preferences, RecallNest now derives structured keys instead of collapsing everything into a broader same-topic key. Examples:
-
-- atomic brand-item preference: `我喜欢吃麦当劳的麦辣鸡翅` -> `preferences:brand-item:麦当劳:麦辣鸡翅`
-- reply-style preference: `User prefers concise, direct replies.` -> `preferences:reply-style:concise:direct`
-- tool-choice preference: `Uses Bun over Node.` -> `preferences:tool-choice:bun:over:node`
-
----
-
-## Capture (Structured Batch Write)
-
-```
-POST /v1/capture
-```
-
-Store multiple structured memories in one request.
-
-> 批量结构化写入：适合上层 agent 一次性提炼多条 durable memory 后统一写入。
-
-**Request:**
-
-```json
-{
-  "scope": "agent:codex",
-  "source": "agent",
-  "defaultImportance": 0.7,
-  "memories": [
-    {
-      "text": "RecallNest is the shared memory layer for Claude Code, Codex, and Gemini CLI",
-      "category": "entities"
-    },
-    {
-      "text": "Use search_memory at task start",
-      "category": "patterns",
-      "importance": 0.9,
-      "tags": ["workflow", "memory"]
-    }
-  ]
-}
-```
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `scope` | string | no | — | Default scope applied to items that do not specify one |
-| `source` | string | no | `"agent"` | Default source for items that do not specify one |
-| `defaultImportance` | number | no | 0.7 | Default importance for items that do not specify one |
-| `memories` | array | yes | — | 1-20 structured memory items |
-
-Each memory item supports:
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `text` | string | yes | — | Memory content |
-| `category` | string | no | `"events"` | Durable memory category |
-| `importance` | number | no | envelope default | Optional per-item override |
-| `scope` | string | no | envelope scope | Optional per-item override; every stored memory still needs a scope via the envelope or item override |
-| `source` | string | no | envelope source | Optional per-item override |
-| `tags` | string[] | no | `[]` | Optional tags |
-| `canonicalKey` | string | no | derived from content | Optional stable key for dedupe/update semantics |
-
-**Response:**
-
-```json
-{
-  "stored": 2,
-  "memories": [
-    {
-      "id": "a1b2c3d4-...",
-      "text": "RecallNest is the shared memory layer for Claude Code, Codex, and Gemini CLI",
-      "category": "entities",
-      "scope": "agent:codex",
-      "source": "agent",
-      "storedAt": "2026-03-16T02:11:00.000Z",
-      "disposition": "stored",
-      "canonicalKey": "entities:recallnest-is-the-shared-memory-layer-for-claude-code-codex-and-gemini-cli"
-    }
-  ]
-}
-```
-
-Each item may also carry `disposition = "conflict"` and a `conflictId` when batch input reuses an existing `canonicalKey` under a different durable category.
-
----
-
-## Pattern (Structured Workflow Capture)
-
-```
-POST /v1/pattern
-```
-
-Store a reusable workflow as durable `patterns` memory.
-
-> 专门写 workflow pattern：适合把“什么时候用、怎么做、做完得到什么”这种可复用流程沉淀成高质量 `patterns` 记忆。
-
-**Request:**
-
-```json
-{
-  "title": "Cross-window continuity handoff",
-  "trigger": "When opening a fresh terminal window for the same project",
-  "steps": [
-    "Call resume_context before coding",
-    "Review stable context and latest checkpoint",
-    "Save checkpoint_session before leaving the window"
-  ],
-  "outcome": "The next window recovers decisions and next actions faster",
-  "tools": ["resume_context", "checkpoint_session"],
-  "importance": 0.9,
-  "source": "agent",
-  "tags": ["continuity", "handoff"]
-}
-```
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `title` | string | yes | — | Short workflow title |
-| `trigger` | string | yes | — | When this workflow should be used |
-| `steps` | string[] | yes | — | Ordered workflow steps, 1-8 items |
-| `outcome` | string | no | — | Optional expected outcome |
-| `tools` | string[] | no | `[]` | Optional tools, commands, or interfaces involved |
-| `importance` | number | no | 0.82 | Importance score (0-1) |
-| `scope` | string | yes | — | Required explicit scope such as `project:recallnest` or `session:abc123` |
-| `source` | string | no | `"agent"` | One of: `manual`, `agent`, `api` |
-| `tags` | string[] | no | `[]` | Optional tags; `workflow` and `pattern` are auto-added |
-| `canonicalKey` | string | no | derived from title | Optional stable key for dedupe/update semantics |
-
-**Response:**
-
-```json
-{
-  "id": "f0e1d2c3-...",
-  "stored": true,
-  "category": "patterns",
-  "title": "Cross-window continuity handoff",
-  "scope": "memory:agent",
-  "tags": ["continuity", "handoff", "workflow", "pattern"],
-  "storedAt": "2026-03-16T08:10:00.000Z"
-}
-```
-
----
-
-## Case (Structured Problem-Solution Capture)
-
-```
-POST /v1/case
-```
-
-Store a reusable problem-solution case as durable `cases` memory.
-
-> 专门写 problem-solution case：适合把“遇到什么问题、怎么解决、最后效果怎样”这种可复用经验沉淀成高质量 `cases` 记忆。
-
-**Request:**
-
-```json
-{
-  "title": "RecallNest sparse startup context cleanup",
-  "problem": "resume_context was returning noisy transcript fragments instead of a clean project handoff",
-  "context": "This happened in a fresh RecallNest window after continuity setup was already in place",
-  "solutionSteps": [
-    "Filter low-signal transcript fragments from stable recall",
-    "Backfill stable context from checkpoint focus, summary, and decisions",
-    "Use a lightweight task focus fallback only when no checkpoint-backed context is available"
-  ],
-  "outcome": "Fresh windows now recover cleaner RecallNest continuity context",
-  "tools": ["resume_context", "checkpoint_session"],
-  "importance": 0.9,
-  "source": "agent",
-  "tags": ["continuity", "startup-context"]
-}
-```
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `title` | string | yes | — | Short case title |
-| `problem` | string | yes | — | What problem happened |
-| `context` | string | no | — | Optional context or preconditions |
-| `solutionSteps` | string[] | yes | — | Ordered solution steps, 1-8 items |
-| `outcome` | string | no | — | Optional result or resolution |
-| `tools` | string[] | no | `[]` | Optional tools, commands, or interfaces involved |
-| `importance` | number | no | 0.84 | Importance score (0-1) |
-| `scope` | string | yes | — | Required explicit scope such as `project:recallnest` or `session:abc123` |
-| `source` | string | no | `"agent"` | One of: `manual`, `agent`, `api` |
-| `tags` | string[] | no | `[]` | Optional tags; `case` and `solution` are auto-added |
-| `canonicalKey` | string | no | derived from title | Optional stable key for dedupe/update semantics |
-
----
-
-## Promote (Evidence -> Durable)
-
-```
-POST /v1/promote
-```
-
-Promote an evidence memory into durable memory.
-
-> 显式升级：把 transcript / import evidence 中的高价值片段升级成 durable memory，而不是让 raw ingest 直接冒充长期事实。
-
-**Request:**
-
-```json
-{
-  "memoryId": "12345678-1234-1234-1234-123456789abc",
-  "text": "User prefers concise, direct replies.",
-  "category": "preferences",
-  "canonicalKey": "user-reply-style",
-  "tags": ["writing"]
-}
-```
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `memoryId` | string | yes | — | Evidence memory ID or unique prefix |
-| `text` | string | no | source text | Optional cleaned durable text |
-| `category` | string | no | inferred from source | Target durable category |
-| `importance` | number | no | 0.78 | Importance score (0-1) |
-| `scope` | string | yes | — | Required explicit target scope such as `project:recallnest` or `session:abc123` |
-| `source` | string | no | `"agent"` | Promotion source label |
-| `tags` | string[] | no | `[]` | Optional tags |
-| `canonicalKey` | string | no | derived from text | Optional stable key for dedupe/update semantics |
-
-**Response:**
-
-```json
-{
-  "id": "c0ffee00-...",
-  "stored": true,
-  "disposition": "promoted",
-  "category": "preferences",
-  "scope": "memory:agent",
-  "sourceMemoryId": "12345678-1234-1234-1234-123456789abc",
-  "sourceCategory": "events",
-  "storedAt": "2026-03-16T02:20:00.000Z",
-  "canonicalKey": "user-reply-style"
-}
-```
-
-When a promotion would overwrite an existing durable memory with the same `canonicalKey`, RecallNest now creates an open conflict candidate instead of silently applying `latest-wins`.
-
-The same slot-aware key inference also applies during promotion when `category = "preferences"` and the text resolves to a supported preference slot such as an atomic brand-item preference, a reply-style preference, or a tool-choice preference.
-
-If the promotion resolves to the same preference slot as the existing durable owner, RecallNest now collapses it onto that owner instead of opening a conflict. This currently applies to slot-aware brand-item keys such as `preferences:brand-item:麦当劳:麦辣鸡翅`, reply-style keys such as `preferences:reply-style:concise:direct`, and tool-choice keys such as `preferences:tool-choice:bun:over:node`.
-
-```json
-{
-  "id": "baddcafe-...",
-  "stored": false,
-  "disposition": "conflict",
-  "category": "preferences",
-  "scope": "memory:agent",
-  "sourceMemoryId": "12345678-1234-1234-1234-123456789abc",
-  "sourceCategory": "events",
-  "storedAt": "2026-03-16T02:20:00.000Z",
-  "canonicalKey": "user-reply-style",
-  "conflictId": "4f71a1f1-..."
-}
-```
-
-Notes:
-
-- `disposition = "promoted"` means a new durable memory was written
-- `disposition = "deduped"` means the durable text already existed under the same `canonicalKey`
-- `disposition = "conflict"` means RecallNest kept the existing durable memory and opened a review item
-
----
-
-## Conflicts
-
-### List / Inspect Conflicts
-
-```
-GET /v1/conflicts
-GET /v1/conflicts?status=open&canonicalKey=user-reply-style&limit=10
-GET /v1/conflicts?attention=stale&limit=10
-GET /v1/conflicts?groupBy=cluster&attention=resolved&limit=10
-GET /v1/conflicts?conflictId=4f71a1f1-...
-```
-
-List recent conflict candidates or fetch a single conflict record.
-
-**List response:**
-
-```json
-{
-  "groupBy": "record",
-  "conflicts": [
-    {
-      "conflictId": "4f71a1f1-...",
-      "status": "open",
-      "reason": "promotion_conflicts_with_existing_durable",
-      "canonicalKey": "user-reply-style",
-      "category": "preferences",
-      "reopenCount": 1,
-      "lastReopenedAt": "2026-03-16T05:20:00.000Z",
-      "lifecycle": {
-        "attention": "aging",
-        "openAgeDays": 1,
-        "reopenCount": 1,
-        "isOpen": true,
-        "needsAttention": false
-      },
-      "advice": {
-        "suggestedResolution": "keep_existing",
-        "confidence": "medium",
-        "similarity": 0.84,
-        "clusterKey": "user-reply-style::promotion_conflicts_with_existing_durable::preferences",
-        "clusterLabel": "preferences / user-reply-style",
-        "reasons": [
-          "Existing durable text already looks like the tighter rewrite."
-        ]
-      },
-      "existing": {
-        "memoryId": "baddcafe-...",
-        "text": "User prefers concise, direct replies."
-      },
-      "incoming": {
-        "sourceMemoryId": "12345678-1234-1234-1234-123456789abc",
-        "text": "User prefers colloquial writing that stays grounded and non-salesy."
-      }
-    }
-  ],
-  "count": 1
-}
-```
-
-**Cluster response:**
-
-```json
-{
-  "groupBy": "cluster",
-  "clusters": [
-    {
-      "clusterKey": "user-reply-style::promotion_conflicts_with_existing_durable::preferences",
-      "clusterLabel": "preferences / user-reply-style",
-      "canonicalKey": "user-reply-style",
-      "category": "preferences",
-      "reason": "promotion_conflicts_with_existing_durable",
-      "totalCount": 3,
-      "openCount": 1,
-      "latestUpdatedAt": "2026-03-16T05:20:00.000Z",
-      "latestConflictId": "4f71a1f1-...",
-      "attentionCounts": {
-        "fresh": 0,
-        "aging": 1,
-        "stale": 0,
-        "escalated": 0,
-        "resolved": 2
-      },
-      "suggestedResolution": "keep_existing",
-      "confidence": "medium"
-    }
-  ],
-  "count": 1
-}
-```
-
-Query parameters:
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `status` | string | Optional raw status filter: `open`, `accepted-incoming`, `kept-existing` |
-| `attention` | string | Optional lifecycle filter: `fresh`, `aging`, `stale`, `escalated`, `resolved` |
-| `groupBy` | string | Optional output mode: `record` (default) or `cluster` |
-| `canonicalKey` | string | Optional canonical key filter |
-| `limit` | number | Max results, default `20` |
-| `conflictId` | string | Fetch a single conflict by full ID or unique prefix |
-
-`advice.mergeSuggestion` is optional. It appears only when RecallNest can derive a conservative merged wording suggestion for `manual_review` conflicts.
-
-**Single conflict response:**
-
-```json
-{
-  "conflict": {
-    "conflictId": "4f71a1f1-...",
-    "status": "open",
-    "canonicalKey": "user-reply-style",
-    "category": "preferences",
-    "lifecycle": {
-      "attention": "aging",
-      "openAgeDays": 1,
-      "reopenCount": 1,
-      "isOpen": true,
-      "needsAttention": false
-    },
-    "advice": {
-      "suggestedResolution": "keep_existing",
-      "confidence": "medium",
-      "similarity": 0.84,
-      "clusterKey": "user-reply-style::promotion_conflicts_with_existing_durable::preferences",
-      "clusterLabel": "preferences / user-reply-style",
-      "reasons": [
-        "Existing durable text already looks like the tighter rewrite."
-      ]
-    }
-  }
-}
-```
-
-### Resolve Conflict
-
-```
-POST /v1/conflicts/resolve
-```
-
-Resolve an open conflict candidate by keeping the existing durable memory, accepting the incoming promoted text, or merging the two into a conservative durable rewrite.
-
-**Request:**
-
-```json
-{
-  "conflictId": "4f71a1f1-...",
-  "resolution": "accept_incoming",
-  "notes": "Incoming wording is cleaner."
-}
-```
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `conflictId` | string | yes | Conflict candidate ID |
-| `resolution` | string | yes | `accept_incoming`, `keep_existing`, or `merge` |
-| `mergedText` | string | no | Optional merged durable wording when `resolution=merge`; otherwise RecallNest uses `advice.mergeSuggestion` when available |
-| `notes` | string | no | Optional operator notes |
-
-**Response:**
-
-```json
-{
-  "conflictId": "4f71a1f1-...",
-  "status": "accepted-incoming",
-  "updatedAt": "2026-03-16T05:00:00.000Z",
-  "resolvedAt": "2026-03-16T05:00:00.000Z",
-  "updatedMemoryId": "baddcafe-..."
-}
-```
-
-If you keep the existing durable memory, `updatedMemoryId` is omitted and the conflict status becomes `kept-existing`.
-If you resolve with `merge`, the conflict status becomes `merged` and `updatedMemoryId` points to the rewritten durable memory that kept the same canonical owner.
-
-### Conflict Audit
-
-```
-GET /v1/conflicts/audit
-GET /v1/conflicts/audit?limit=100&top=5
-GET /v1/conflicts/audit?canonicalKey=user-reply-style
-```
-
-Generate a terminal-friendly audit summary so stale or escalated clusters can be reviewed first.
-
-**Response:**
-
-```json
-{
-  "totalConflicts": 7,
-  "totalClusters": 3,
-  "openConflicts": 4,
-  "openClusters": 2,
-  "attentionCounts": {
-    "fresh": 1,
-    "aging": 1,
-    "stale": 1,
-    "escalated": 1,
-    "resolved": 3
-  },
-  "priorityClusters": [
-    {
-      "clusterKey": "user-reply-style::promotion_conflicts_with_existing_durable::preferences",
-      "clusterLabel": "preferences / user-reply-style",
-      "canonicalKey": "user-reply-style",
-      "category": "preferences",
-      "reason": "promotion_conflicts_with_existing_durable",
-      "totalCount": 4,
-      "openCount": 2,
-      "latestUpdatedAt": "2026-03-16T05:20:00.000Z",
-      "latestConflictId": "4f71a1f1-...",
-      "attention": "escalated",
-      "suggestedResolution": "keep_existing",
-      "confidence": "medium"
-    }
-  ],
-  "suggestedActions": [
-    "Resolve 1 escalated cluster(s) first."
-  ]
-}
-```
-
-Query parameters:
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `status` | string | Optional raw status filter: `open`, `accepted-incoming`, `kept-existing` |
-| `canonicalKey` | string | Optional canonical key filter |
-| `limit` | number | Max records to scan, default `100` |
-| `top` | number | Max priority clusters to return, default `5` |
-
-### Escalate Conflicts
-
-```
-POST /v1/conflicts/escalate
-```
-
-Preview or apply escalation metadata for `stale` / `escalated` open conflicts.
-
-**Request:**
-
-```json
-{
-  "attention": "stale",
-  "limit": 100,
-  "top": 10,
-  "apply": false,
-  "notes": "nightly escalation audit"
-}
-```
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `attention` | string | no | `stale` or `escalated`, default `stale` |
-| `canonicalKey` | string | no | Optional canonical key filter |
-| `limit` | number | no | Max open conflicts to scan, default `100` |
-| `top` | number | no | Max eligible conflicts to include, default `10` |
-| `apply` | boolean | no | When `false`, preview only. When `true`, writes escalation metadata |
-| `notes` | string | no | Optional operator note stored on escalated conflicts |
-
-**Response:**
-
-```json
-{
-  "apply": false,
-  "scanned": 12,
-  "eligible": 2,
-  "escalated": 0,
-  "skipped": 0,
-  "items": [
-    {
-      "conflictId": "4f71a1f1-...",
-      "canonicalKey": "user-reply-style",
-      "attention": "stale",
-      "openAgeDays": 4,
-      "reopenCount": 1,
-      "escalationCount": 0,
-      "suggestedResolution": "manual_review",
-      "confidence": "high",
-      "action": "pending",
-      "clusterKey": "user-reply-style::promotion_conflicts_with_existing_durable::preferences"
-    }
-  ]
-}
-```
-
----
-
-## Checkpoint (Save Current Work State)
-
-```
-POST /v1/checkpoint
-```
-
-Store a session checkpoint outside the durable memory index.
-
-> 保存当前工作状态：适合跨窗口延续任务，但不应该混入长期 durable memory。
-
-**Request:**
-
-```json
-{
-  "sessionId": "codex-2026-03-16-001",
-  "scope": "agent:codex",
-  "summary": "Implement session checkpoint storage",
-  "decisions": ["Keep checkpoints out of LanceDB"],
-  "openLoops": ["Need resume_context next"],
-  "nextActions": ["Add checkpoint MCP tool"],
-  "entities": ["RecallNest", "Codex"],
-  "files": ["src/session-store.ts"]
-}
-```
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `sessionId` | string | yes | — | Current session identifier |
-| `scope` | string | no | `session:{sessionId}` | Optional shared scope |
-| `summary` | string | yes | — | Compact summary of the current work state |
-| `task` | string | no | — | Optional task label |
-| `decisions` | string[] | no | `[]` | Key decisions already made |
-| `openLoops` | string[] | no | `[]` | Unresolved questions or pending items |
-| `nextActions` | string[] | no | `[]` | Next actions to take |
-| `entities` | string[] | no | `[]` | Relevant projects, tools, or people |
-| `files` | string[] | no | `[]` | Relevant files or paths |
-| `updatedAt` | string | no | `now()` | Optional ISO timestamp override |
-
-RecallNest sanitizes repo-state text such as `git status`, modified-file lists, and untracked-file notes out of saved checkpoint content. Verify volatile repo state locally in the next window instead of relying on checkpoint text.
-Managed MCP / HTTP checkpoint calls now also append a dedicated workflow observation automatically: normal saves record `success`, while repo-state sanitization records `corrected` with signal `repo-state-sanitized`.
-
-**Response:**
-
-```json
-{
-  "sessionId": "codex-2026-03-16-001",
-  "scope": "agent:codex",
-  "summary": "Implement session checkpoint storage",
-  "decisions": ["Keep checkpoints out of LanceDB"],
-  "openLoops": ["Need resume_context next"],
-  "nextActions": ["Add checkpoint MCP tool"],
-  "entities": ["RecallNest", "Codex"],
-  "files": ["src/session-store.ts"],
-  "updatedAt": "2026-03-16T09:30:00.000Z"
-}
-```
-
----
-
-## Resume (Compose Startup Context)
-
-```
-POST /v1/resume
-```
-
-Compose startup context for a fresh window by combining stable durable memory, relevant patterns and cases, plus the latest checkpoint for a session or scope.
-
-> 为新窗口编排上下文：返回的是组合后的连续性上下文，不是原始检索结果堆积。
-
-Managed MCP / HTTP resume calls now also append a dedicated `resume_context` workflow observation with source `managed`; this stays in the workflow observation store and does not enter durable recall.
-
-**Request:**
-
-```json
-{
-  "task": "Implement startup continuity for fresh windows",
-  "scope": "agent:codex",
-  "sessionId": "codex-2026-03-16-001",
-  "limitPerSection": 3,
-  "includeLatestCheckpoint": true,
-  "profile": "default"
-}
-```
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `task` | string | no | — | Optional current task or question to bias recall |
-| `scope` | string | no | — | Optional shared scope for project or terminal continuity |
-| `sessionId` | string | no | — | Optional session identifier used to recover the latest checkpoint |
-| `limitPerSection` | number | no | 3 | Max items returned per section (1-6) |
-| `includeLatestCheckpoint` | boolean | no | `true` | Whether to include the latest checkpoint summary |
-| `profile` | string | no | `"default"` | Retrieval profile: `default`, `writing`, `debug`, `fact-check` |
-
-**Response:**
-
-```json
-{
-  "summary": "Loaded 3 stable context item(s), 2 pattern(s), and 1 case(s). Latest checkpoint from codex-2026-03-16-001 on 2026-03-16: Implement startup continuity for fresh windows.",
-  "resolvedScope": "agent:codex",
-  "stableContext": [
-    "Profile: User builds local-first memory systems.",
-    "Preference: User prefers concise technical replies.",
-    "Entity: RecallNest is shared across Claude Code, Codex, and Gemini CLI."
-  ],
-  "relevantPatterns": [
-    "At task start, run search_memory before coding."
-  ],
-  "recentCases": [
-    "Keep session state in a checkpoint store instead of the durable index."
-  ],
-  "latestCheckpoint": {
-    "sessionId": "codex-2026-03-16-001",
-    "resolvedScope": "agent:codex",
-    "summary": "Implement startup continuity for fresh windows",
-    "updatedAt": "2026-03-16T05:00:00.000Z"
-  },
-  "generatedAt": "2026-03-16T05:10:00.000Z",
-  "profile": "default"
-}
-```
-
-Use `resolvedScope` as the default scope for follow-up `search_memory`, `brief_memory`, `pin_memory`, and similar recall calls when the client did not already provide a stricter shared scope.
-
----
-
-## Latest Checkpoint
-
-```
-GET /v1/checkpoint/latest
-```
-
-Fetch the latest checkpoint for a given `sessionId` or `scope`.
-
-> 获取最新 checkpoint：适合调试当前工作状态是否已写入，也可以和 `POST /v1/resume` 配合使用。
-
-Query params:
-
-| Param | Required | Description |
-|-------|----------|-------------|
-| `sessionId` | no | Filter by session ID |
-| `scope` | no | Filter by shared scope |
-
-**Response:**
-
-```json
-{
-  "checkpoint": {
-    "sessionId": "codex-2026-03-16-001",
-    "summary": "Implement session checkpoint storage",
-    "updatedAt": "2026-03-16T03:20:00.000Z",
-    "checkpointId": "b1c2d3e4-...",
-    "resolvedScope": "agent:codex"
-  }
-}
-```
-
-If nothing matches:
-
-```json
-{
-  "checkpoint": null
-}
-```
-
----
-
-## Workflow Observe
-
-```
-POST /v1/workflow-observe
-```
-
-Store one append-only workflow observation outside durable memory.
-
-> 记录 workflow observation：适合追踪 `resume_context`、`checkpoint_session` 等 primitive 是成功、失败、被纠正，还是被漏掉。
-
-**Request:**
-
-```json
-{
-  "workflowId": "resume_context",
-  "outcome": "missed",
-  "summary": "Fresh window skipped continuity recovery before repo exploration.",
-  "scope": "project:recallnest",
-  "source": "smoke",
-  "signal": "missed-startup-trigger",
-  "task": "headless continuity smoke",
-  "tags": ["continuity"],
-  "tools": ["resume_context"]
-}
-```
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `workflowId` | string | yes | — | Workflow primitive id such as `resume_context` |
-| `outcome` | string | no | `"success"` | One of: `success`, `failure`, `corrected`, `missed` |
-| `summary` | string | yes | — | Short description of what happened |
-| `scope` | string | no | `"global"` | Optional scope such as `project:recallnest` |
-| `source` | string | no | `"manual"` | Source label such as `agent`, `managed`, `smoke`, `eval`, `manual` |
-| `signal` | string | no | — | Optional failure/correction signal tag |
-| `task` | string | no | — | Optional related task |
-| `tags` | string[] | no | `[]` | Optional tags |
-| `tools` | string[] | no | `[]` | Optional tools involved |
-| `recordedAt` | string | no | `now()` | Optional ISO timestamp override |
-
-**Response:**
-
-```json
-{
-  "observationId": "resume_context-missed-2026-03-17T03-00-00-000Z",
-  "workflowId": "resume_context",
-  "outcome": "missed",
-  "summary": "Fresh window skipped continuity recovery before repo exploration.",
-  "scope": "project:recallnest",
-  "resolvedScope": "project:recallnest",
-  "source": "smoke",
-  "signal": "missed-startup-trigger",
-  "task": "headless continuity smoke",
-  "tags": ["continuity"],
-  "tools": ["resume_context"],
-  "recordedAt": "2026-03-17T03:00:00.000Z"
-}
-```
-
----
-
-## Workflow Health
-
-```
-GET /v1/workflow-health
-GET /v1/workflow-health?workflowId=resume_context&scope=project:recallnest
-```
-
-Inspect one workflow primitive or return a dashboard of degraded workflows.
-
-> 查看 workflow 健康度：支持单个 workflow 的 7 天 / 30 天汇总，也支持全局 dashboard。
-
-Query params:
-
-| Param | Required | Description |
-|-------|----------|-------------|
-| `workflowId` | no | Optional workflow primitive id |
-| `scope` | no | Optional scope filter |
-| `limit` | no | Dashboard max rows, default `10` |
-
-**Workflow response:**
-
-```json
-{
-  "workflowId": "resume_context",
-  "scope": "project:recallnest",
-  "status": "watch",
-  "summary": "3 observations in the last 30d, success rate 33.3%, 2 issue observations.",
-  "latestObservationAt": "2026-03-17T03:00:00.000Z",
-  "windows": [
-    {
-      "days": 7,
-      "total": 2,
-      "successes": 1,
-      "failures": 0,
-      "corrected": 1,
-      "missed": 0,
-      "issueCount": 1,
-      "successRate": 0.5,
-      "issueRate": 0.5,
-      "latestAt": "2026-03-17T03:00:00.000Z",
-      "topSignals": [
-        { "signal": "user-correction", "count": 1 }
-      ]
-    }
-  ]
-}
-```
-
-**Dashboard response:**
-
-```json
-{
-  "dashboard": [
-    {
-      "workflowId": "checkpoint_session",
-      "scope": "project:recallnest",
-      "status": "critical",
-      "total": 1,
-      "issueCount": 1,
-      "successRate": 0,
-      "latestObservationAt": "2026-03-17T04:00:00.000Z",
-      "summary": "1 observations in the last 30d, success rate 0.0%, 1 issue observations."
-    }
-  ]
-}
-```
-
----
-
-## Workflow Evidence
-
-```
-GET /v1/workflow-evidence?workflowId=checkpoint_session&scope=project:recallnest&limit=5
-```
-
-Build an evidence pack for one workflow primitive from recent issue observations.
-
-> 生成 workflow evidence pack：把最近问题 observation、top signals 和修复建议打包出来，方便做规则、prompt、测试收口。
-
-Query params:
-
-| Param | Required | Description |
-|-------|----------|-------------|
-| `workflowId` | yes | Workflow primitive id |
-| `scope` | no | Optional scope filter |
-| `limit` | no | Max recent issue observations, default `5` |
-
-**Response:**
-
-```json
-{
-  "workflowId": "checkpoint_session",
-  "scope": "project:recallnest",
-  "generatedAt": "2026-03-17T10:10:00.000Z",
-  "summary": "1 issue observations in the last 30d for checkpoint_session.",
-  "topSignals": [
-    { "signal": "repo-state-contamination", "count": 1 }
-  ],
-  "recentIssues": [
-    {
-      "observationId": "checkpoint_session-failure-2026-03-17T04-00-00-000Z",
-      "outcome": "failure",
-      "summary": "Checkpoint still carried repo-state text before the product-side guard landed.",
-      "signal": "repo-state-contamination",
-      "recordedAt": "2026-03-17T04:00:00.000Z",
-      "task": "headless continuity smoke"
-    }
-  ],
-  "suggestions": [
-    "Keep volatile repo-state text out of saved checkpoints and handoff summaries unless this window verified it."
-  ]
-}
-```
-
----
-
-## Search (Advanced)
-
-```
-POST /v1/search
-```
-
-Advanced search with full metadata, retrieval path details, and scope filtering.
-
-> 高级搜索：返回完整元数据、检索路径、重要度等详情。
-
-**Request:**
-
-```json
-{
-  "query": "API authentication patterns",
-  "limit": 5,
-  "category": "patterns",
-  "profile": "fact-check"
-}
-```
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `query` | string | yes | — | Search query |
-| `limit` | number | no | 5 | Max results (1-20) |
-| `category` | string | no | — | Filter: `profile`, `preferences`, `entities`, `events`, `cases`, `patterns` |
-| `profile` | string | no | `"default"` | Retrieval profile: `default`, `writing`, `debug`, `fact-check` |
-| `scope` | string | no | — | Filter by source scope (e.g. `cc`, `codex`, `api:my-agent`) |
-| `minScore` | number | no | 0 | Minimum relevance score (0-1) |
-
-**Response:**
-
-```json
-{
-  "results": [
-    {
-      "id": "a1b2c3d4-...",
-      "text": "Authentication pattern: use JWT with...",
-      "category": "patterns",
-      "scope": "cc:abc12345",
-      "score": 0.82,
-      "importance": 0.8,
-      "timestamp": 1741219200000,
-      "date": "2026-03-06",
-      "metadata": { "source": "cc", "tier": "working", "file": "..." },
-      "boundary": {
-        "layer": "durable",
-        "authority": "structured-memory",
-        "conflictPolicy": "latest-wins",
-        "originalCategory": "patterns"
-      },
-      "canonicalKey": "patterns:cross-window-continuity-handoff",
-      "promotedFrom": null,
-      "sources": { "vector": { "score": 0.85, "rank": 1 }, "bm25": { "score": 0.7, "rank": 3 } }
-    }
-  ],
-  "query": "API authentication patterns",
-  "profile": "fact-check",
-  "count": 1
-}
-```
-
-Derived provenance fields:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `boundary` | object \| null | Parsed boundary metadata: `layer`, `authority`, `conflictPolicy`, and optional `originalCategory` / `downgradedFrom` |
-| `canonicalKey` | string \| null | Stable dedupe/update key if the memory has one |
-| `promotedFrom` | object \| null | Present when a durable memory was explicitly promoted from evidence; includes source `memoryId`, `scope`, `category`, `source`, and source `boundary` |
-| `provenanceHistory` | array | Observed evidence trail for the durable memory. Falls back to `[promotedFrom]` when no explicit history has been materialized yet |
-| `provenanceHistoryCount` | number | Total provenance-history observations tracked for the durable memory |
-
----
-
-## Stats
-
-```
-GET /v1/stats
-```
-
-Memory index statistics.
-
-**Response:**
-
-```json
-{
-  "totalMemories": 35176,
-  "byScope": {
-    "cc:abc12345": 773,
-    "memory": 974,
-    "codex:019ccbe4": 277
-  },
-  "byCategory": {
-    "fact": 31582,
-    "events": 1546,
-    "cases": 1337,
-    "entities": 455,
-    "patterns": 156,
-    "preferences": 65,
-    "profile": 26
-  }
-}
-```
-
-> Note: `byScope` shows raw scope keys. Use `byCategory` for the 6-category distribution.
-
----
-
-## Consolidate (Phase 3 — not yet implemented)
-
-```
-POST /v1/consolidate
-```
-
-> This endpoint is planned for Phase 3 (self-evolution). See [docs/self-evolution.md](self-evolution.md) for the design.
-
----
-
-## Gaps (Phase 3 — not yet implemented)
-
-```
-GET /v1/gaps
-```
-
-> This endpoint is planned for Phase 3 (self-evolution). See [docs/self-evolution.md](self-evolution.md) for the design.
-
----
-
-## Error Responses
-
-All endpoints return errors in this format:
-
-```json
-{
-  "error": "Description of what went wrong"
-}
-```
-
-| HTTP Status | Meaning |
-|-------------|---------|
-| 400 | Bad request (missing required fields, invalid values) |
-| 404 | Endpoint not found |
-| 500 | Internal server error |
-| 503 | Service unavailable (health check failed) |
-
----
-
-## Quick Test
-
-```bash
-# Health check
-curl http://localhost:4318/v1/health
-
-# Recall
-curl -X POST http://localhost:4318/v1/recall \
-  -H "Content-Type: application/json" \
-  -d '{"query": "Docker debugging", "limit": 3}'
-
-# Store
-curl -X POST http://localhost:4318/v1/store \
-  -H "Content-Type: application/json" \
-  -d '{"text": "Test memory entry", "category": "events"}'
-
-# Advanced search with category filter
-curl -X POST http://localhost:4318/v1/search \
-  -H "Content-Type: application/json" \
-  -d '{"query": "debugging", "category": "cases", "profile": "debug"}'
-
-# Stats
-curl http://localhost:4318/v1/stats
-```