memorix 1.8.3 → 1.8.5

package/dist/memcode-runtime/CHANGELOG.md

@@ -4,6 +4,59 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [1.8.5] - 2026-08-30
+
+### Fixed
+- **Modern MCP transport** -- `memorix serve` and the HTTP control plane now
+  use the official MCP v2 server path for 2026-07-28 discovery, request
+  metadata, result envelopes, response metadata, stateless requests, and the
+  subscriptions listen surface while forwarding business tools through the
+  existing Memorix implementation.
+- **Background start race (#259)** -- background startup now holds an
+  exclusive, heartbeating lock across the check/spawn/readiness window. Lock
+  contention fails closed with a retry message instead of starting an unlocked
+  duplicate control plane; stale dead-owner locks are recoverable.
+- **Windows and EOF behavior** -- stdio discovery remains compatible before
+  and after readiness, roots-based project switching and deferred maintenance
+  are preserved, and stdin EOF closes the official transport cleanly.
+- **Local build reliability** -- the large runtime, CLI, and memcode bundles
+  build sequentially, reducing Windows memory pressure without changing
+  published entry points. Slow CLI uninstall tests now use asynchronous,
+  hidden child processes so the full test run exits cleanly.
+- **Time-stable graph evaluation** -- graph-context fixtures pin their
+  reference date so retention policy changes do not make the test depend on the
+  calendar.
+
+### MCP Compatibility Boundary
+- Modern Tasks are explicitly unsupported because Memorix does not expose a
+  durable task store for MCP task semantics.
+- List responses expose a private zero-TTL protocol hint; Memorix does not
+  claim a reusable server-side list cache.
+- The external `@hasmcp/mcp-spec-test` runner currently fails on this Windows
+  host before reaching the target because it imports drive-letter paths as ESM
+  URLs. Production verification therefore includes official v2 direct tests,
+  real stdio/HTTP smoke, and the legacy compatibility path; this external
+  runner result is not reported as a pass.
+
+## [1.8.4] - 2026-08-27
+
+### Fixed
+- **Stateless HTTP MCP requests (#255)** -- clients such as Claude Code that
+  send the current protocol header on every request can list and call tools
+  without echoing a custom project handle. Durable handles are still created
+  on `initialize` and remain available when a client opts into them.
+- **MCP protocol self-description (#257)** -- discovery and HTTP response
+  headers now advertise the legacy revisions implemented by the pinned SDK,
+  instead of claiming complete support for the newer 2026 revision.
+- **MCP stdio smoke contract** -- the release smoke script now checks the
+  truthful advertised revision set after the compatibility fix.
+
+### MCP Compatibility
+- The 1.8.4 line supports legacy stateful MCP, versionless stdio tool calls,
+  pre-initialize discovery, and the narrow stateless HTTP compatibility path.
+  It does not claim full 2026 result metadata, Tasks, subscriptions, or list
+  caching support.
+
 ## [1.8.3] - 2026-08-25
 
 ### Fixed

package/dist/sdk.js

@@ -162443,6 +162443,9 @@ var init_official_skills = __esm({
           '| Specific past decision, bug, file, or change | `memorix_search` | `memorix memory search --query "<topic>"` |',
           "| Need the full source for a search hit | `memorix_detail` | `memorix memory detail --id <id>` |",
           "| Need the sequence around one memory | `memorix_timeline` | `memorix memory timeline --id <id>` |",
+          "| Check source and freshness for a memory | `memorix_evidence` | `memorix evidence list|get|events` |",
+          "| Record whether a memory helped, conflicted, or was corrected | `memorix_feedback` | `memorix feedback record|show|audit` |",
+          "| Inspect or import controlled media | `memorix_media` | `memorix media import|attach|list|show|status` |",
           '| Learned reusable project knowledge | `memorix_store` | `memorix memory store --type <type> --entity <name> --title "<title>" "<text>"` |',
           "| Task or bug is complete/outdated | `memorix_resolve` | `memorix memory resolve --ids <ids>` |",
           "",
@@ -162573,6 +162576,8 @@ var init_official_skills = __esm({
           "",
           "Promote memories into mini-skills only when they are reusable instructions, not just historical notes.",
           "",
+          "The standard setup uses the `lite` MCP profile. `memorix_skills` and `memorix_promote` are full-profile tools, so use the CLI fallback unless the current server was explicitly started with `MEMORIX_MODE=full` or `--mode full`. Do not probe hidden MCP tools repeatedly.",
+          "",
           "## Tool Router",
           "",
           "| Situation | Prefer | CLI fallback |",
@@ -162608,15 +162613,17 @@ var init_official_skills = __esm({
           "| Situation | Prefer | CLI fallback |",
           "|---|---|---|",
           '| Run managed subagent execution | CLI | `memorix orchestrate --goal "<goal>" --agents claude:1,codex:1` |',
-          "| Register coordination identity | `team_manage` action `join` | `memorix team join --agentType <agent>` |",
-          "| Create or inspect tasks | `team_task` | `memorix task create|list|claim|complete` |",
-          "| Send or read coordination messages | `team_message` | `memorix message send|broadcast|inbox` |",
-          "| Share structured handoff | `memorix_handoff` | `memorix handoff send` |",
-          "| Avoid file conflicts | `team_file_lock` | `memorix lock lock|unlock|status` |",
-          "| Poll joined coordination state | `memorix_poll` | `memorix poll` |",
+          "| Register coordination identity when team MCP tools are available | `team_manage` action `join` | `memorix team join --agentType <agent>` |",
+          "| Create or inspect tasks when team MCP tools are available | `team_task` | `memorix task create|list|claim|complete` |",
+          "| Send or read coordination messages when team MCP tools are available | `team_message` | `memorix message send|broadcast|inbox` |",
+          "| Share structured handoff when team MCP tools are available | `memorix_handoff` | `memorix handoff send` |",
+          "| Avoid file conflicts when team MCP tools are available | `team_file_lock` | `memorix lock lock|unlock|status` |",
+          "| Poll joined coordination state when team MCP tools are available | `memorix_poll` | `memorix poll` |",
           "",
           "## Boundaries",
           "",
+          "The standard setup uses the `lite` MCP profile. Coordination MCP tools are exposed only by `team` or `full`; use the CLI fallback for ordinary installations, or explicitly start the server with `--mode team`. Do not probe unavailable team tools in a loop.",
+          "",
           "- For ordinary memory, do not join coordination state.",
           "- For production multi-agent execution, prefer `memorix orchestrate` so the main process owns planning, dispatch, retries, and verification gates.",
           "- `memorix orchestrate` uses the current checkout for single-worker runs and task worktrees for parallel runs. Use `--isolated` to force worktree isolation, `--no-worktree` to disable it, `--allow-dirty` to run with uncommitted changes, and `--no-auto-merge` to preserve task worktrees for manual review.",
@@ -163780,7 +163787,10 @@ alwaysApply: true
     "| `memorix_store` | Save something worth persisting |",
     '| `memorix_store_reasoning` | Save the "why" behind a decision |',
     "| `memorix_resolve` | Mark completed/outdated memories |",
-    "| `memorix_session_start` | Load session context (handoff, orchestration coordination) |"
+    "| `memorix_session_start` | Load session context (handoff, orchestration coordination) |",
+    "| `memorix_evidence` | Check a memory source, freshness, and verification state |",
+    "| `memorix_feedback` | Record whether a memory helped, conflicted, or was corrected |",
+    "| `memorix_media` | Inspect or import controlled local media |"
   ].join("\n");
 }
 async function uninstallHooks(agent, projectRoot, global2 = false) {
@@ -167662,16 +167672,24 @@ function resolveToolProfile(opts) {
   return normalize(opts.explicit) ?? normalize(opts.envValue) ?? opts.fallback;
 }
 function describeProfile(profile) {
+  const count2 = countToolsInProfile(profile);
   switch (profile) {
     case "micro":
-      return "micro (agent-ready context + bounded recovery/media, ~9 tools)";
+      return `micro (agent-ready context + bounded recovery/media, ${count2} tools)`;
     case "lite":
-      return "lite (core memory + sessions, ~18 tools)";
+      return `lite (core memory + sessions, ${count2} tools)`;
     case "team":
-      return "team (lite + coordination tools + dashboard + knowledge workspace, ~26 tools)";
+      return `team (lite + coordination tools + dashboard + knowledge workspace, ${count2} tools)`;
     case "full":
-      return "full (all tools including advanced / KG-compat)";
+      return `full (all tools including advanced / KG-compat, ${count2} tools)`;
+  }
+}
+function countToolsInProfile(profile) {
+  let n = 0;
+  for (const name of Object.keys(TOOL_PROFILES)) {
+    if (isToolInProfile(name, profile)) n++;
   }
+  return n;
 }
 
 // src/server.ts
@@ -167809,7 +167827,6 @@ import { z as z625 } from "zod/v4";
 
 // src/server/mcp-discovery.ts
 init_esm_shims();
-var MCP_MODERN_PROTOCOL_VERSION = "2026-07-28";
 var MCP_LEGACY_PROTOCOL_VERSION = "2025-11-25";
 var MCP_OLDEST_LEGACY_PROTOCOL_VERSION = "2024-11-05";
 var MCP_SERVER_DISCOVER_METHOD = "server/discover";
@@ -167817,14 +167834,13 @@ var MCP_SERVER_INFO_META_KEY = "io.modelcontextprotocol/serverInfo";
 function getMcpServerInfo() {
   return {
     name: "memorix",
-    version: true ? "1.8.3" : "1.0.1"
+    version: true ? "1.8.5" : "1.0.1"
   };
 }
 function createMcpDiscoverResult(capabilities, serverInfo) {
   return {
     resultType: "complete",
     supportedVersions: [
-      MCP_MODERN_PROTOCOL_VERSION,
       MCP_LEGACY_PROTOCOL_VERSION,
       MCP_OLDEST_LEGACY_PROTOCOL_VERSION
     ],

package/docs/1.8.0-RELEASE-CANDIDATE-SPEC.md

@@ -1,6 +1,9 @@
-# Memorix 1.8.0 Release Candidate Specification
+# Memorix 1.8.5 Release Acceptance Specification
 
-Status: accepted implementation contract for Memorix 1.8.0.
+Status: accepted implementation contract for Memorix 1.8.5.
+
+This document keeps its historical filename for link stability. The current
+release contract supersedes the original 1.8.0 wording below.
 
 ## Acceptance Checklist
 
@@ -14,22 +17,25 @@ Status: accepted implementation contract for Memorix 1.8.0.
 - [x] Provide dashboard evidence/provenance views without replacing the existing UI.
 - [x] Preserve explicit project/session handles across restart and client shapes.
 - [x] Verify CLI fallback, Windows child-process hiding, HTTP old/new smoke, build, and package contents.
+- [x] Add the official MCP v2 transport path while retaining legacy clients.
+- [x] Reject unsupported durable Tasks explicitly instead of returning fake success.
 
 ## Compatibility Contract
 
 Memorix preserves the legacy 2025-era initialize contract, including stdio and
-stateful Streamable HTTP with `Mcp-Session-Id`. Memorix 1.8.3 also registers a
-low-level `server/discover` compatibility adapter for the 2026-07-28 request.
-Its `DiscoverResult` is complete for the required identity, versions,
-capabilities, and private zero-TTL cache hint. Versionless `tools/list` and
-`tools/call` are accepted by the pinned v1 SDK and retain its legacy result
-envelopes. The stdio startup gate reads bounded newline-delimited input before
-project initialization, answers discovery immediately, and replays all other
-messages in order; EOF is deferred until the queued input is released. HTTP
-stateless project handles remain a compatibility adapter: they
-own project routing, but do not turn the v1 SDK into a complete 2026 runtime.
-Tasks, subscriptions, and list-response caching are unsupported and are not
-advertised or simulated.
+stateful Streamable HTTP with `Mcp-Session-Id`. Memorix 1.8.5 uses the official
+MCP v2 transport for the modern stateless path and retains the legacy bridge
+for existing clients. The `server/discover` result is complete for the
+supported identity, versions, capabilities, result metadata, and private
+zero-TTL cache hint. Versionless `tools/list` and `tools/call` remain accepted
+for legacy clients. The stdio startup gate reads bounded newline-delimited
+input before project initialization, answers early discovery, and replays all
+other messages in order; EOF is deferred until queued input is released.
+Stateless HTTP project handles own project routing on the modern path.
+Subscriptions are supported with the official listen surface. Durable Tasks
+remain unsupported and are rejected explicitly because Memorix does not yet
+have a durable MCP task contract; list responses carry a zero-TTL hint rather
+than pretending to have a reusable server-side cache.
 
 Antigravity is the primary setup target. Gemini CLI remains a compatibility and
 migration path. GitHub issue #204 (WorkBuddy) is intentionally not merged or
@@ -73,8 +79,8 @@ is rejected for that task window.
 
 ## Explicit Non-goals for 1.8.0
 
-- No fake MCP Tasks/polling implementation when the pinned SDK does not expose
-  a durable server-side task contract.
+- No fake MCP Tasks/polling implementation when Memorix does not expose a
+  durable server-side task contract.
 - No remote memory hub, proxying of model traffic, or upstream installer.
 - No claim that the bundled Lite parser is a semantic CodeGraph.
 - No marketing landing page in place of an operator evidence console.

package/docs/AGENT_OPERATOR_PLAYBOOK.md

@@ -137,7 +137,7 @@ when the user wants:
 - explicit task/message/handoff/lock coordination
 - one shared HTTP service process
 
-Default recommendation: if the user wants memory inside an existing IDE or agent, start with `memorix setup --agent <agent> --global`. Use `memorix serve` only for manual MCP wiring. Use the CLI for direct workflows and automation because it does not depend on an IDE's MCP session lifecycle. Use memcode only when the user wants the bundled terminal agent. Reach for HTTP only when a shared background service, multi-client MCP access, Docker, or a live dashboard endpoint is actually needed.
+Default recommendation: if the user wants memory inside an existing IDE or agent, start with `memorix setup --agent <agent> --global`. Use `memorix serve` only for manual MCP wiring. Use the CLI for direct workflows and automation because it does not depend on an IDE's MCP session lifecycle. Use memcode only when the user wants the bundled terminal agent. Reach for HTTP only when a shared background service, multi-client MCP access, a VPS Docker deployment, or a live dashboard endpoint is actually needed. Local development runs Node directly.
 
 Use:
 
@@ -826,7 +826,7 @@ read this document first, then act.
 This playbook is the canonical AI-facing guide for installation, project binding, integration, hooks, troubleshooting, and safe usage.
 ## Docker Note
 
-When Memorix runs in Docker, treat it as an **HTTP service deployment**, not a stdio MCP process.
+When Memorix runs in Docker on a VPS/hosted machine, treat it as an **HTTP service deployment**, not a stdio MCP process. Docker is not required for local development.
 
 - Connect IDEs and agents to `http://host:3211/mcp`
 - Use `memorix_session_start(projectRoot=...)` with a path that is visible **inside** the container

package/docs/API_REFERENCE.md

@@ -28,7 +28,7 @@ Use **MCP** when:
 Use the **CLI** when:
 
 - you want to inspect or change project state from a terminal
-- you are on SSH / Docker / CI / NAS and want direct commands
+- you are on SSH / VPS Docker / CI / NAS and want direct commands
 - you want readable, namespaced actions instead of raw MCP tool payloads
 - you want full access to Memorix CLI capabilities without depending on an MCP client
 
@@ -150,17 +150,19 @@ feedback projection.
 ### MCP Compatibility
 
 Legacy clients use stateful Streamable HTTP with `Mcp-Session-Id` and the
-2025-era `initialize` handshake. The 1.8.3 stdio server starts a bounded
+2025-era `initialize` handshake. The 1.8.5 stdio server starts a bounded
 newline-delimited JSON-RPC gate before project initialization: it answers the
 2026-07-28 `server/discover` request before `initialize`, then replays other
 requests, notifications, and responses in order into the pinned SDK transport.
 Versionless `tools/list` and `tools/call` use the SDK's legacy result envelopes.
-HTTP stateless clients may use a durable
-`Mcp-Project-Handle`; `/protocol-diagnostics` labels this as compatibility-only.
-Modern result metadata is discovery-only with a private zero-TTL hint. Tasks,
-subscriptions, and list-response caching are unsupported. When MCP discovery
-is unavailable, use one bounded `memorix context --fallback` request for a
-task; repeated fallback probing is rejected by the local budget.
+HTTP modern clients may use the stateless `2026-07-28` path and a durable
+`Mcp-Project-Handle`; `/protocol-diagnostics` reports this as supported.
+Modern result metadata is returned for discovery, list, and call responses.
+The official subscriptions listen surface is available, but Memorix has no
+durable Tasks implementation, so task requests remain explicitly unsupported.
+List responses carry a private zero-TTL hint, not a reusable server-side cache.
+When MCP discovery is unavailable, use one bounded `memorix context --fallback`
+request for a task; repeated fallback probing is rejected by the local budget.
 
 The built-in Lite provider indexes common code files with lightweight file, symbol, and import facts. It is a structural fallback, not a language-server-quality graph. When a project already has a healthy local CodeGraph index, `[codegraph].external_context = "auto"` may add a validated, bounded semantic outline to the Workset. Memorix never initializes, syncs, or exports that external index, and never stores its raw source output. `memorix codegraph status --json`, `memorix doctor --json`, and Project Context JSON identify the actual provider quality.
 

package/docs/DASHBOARD.md

@@ -7,6 +7,19 @@ used by MCP and CLI. It shows each card's source reference, locator, captured
 hash, freshness, verification state, and audit-event count. It is project
 scoped and does not replace the underlying observation or code source.
 
+## Surface Boundaries
+
+Each Dashboard page maps to a real data surface: Overview shows overall state,
+Git Memory shows Git-derived memory, Knowledge shows source-backed knowledge
+pages, Memory Map shows the evidence-backed relation projection, Observations
+and Evidence show records and provenance, Retention/Config/Identity show
+runtime health, and Sessions/Coordination show session and persistent
+coordination state.
+
+These pages are not demo panels. Empty data is shown as empty, and failed reads
+are shown as unavailable; the UI does not substitute another data model or old
+graph renderer to make a result look healthy.
+
 ## Start
 
 ```bash
@@ -25,6 +38,16 @@ The Coordination Status page is a read-only projection of the selected project's
 
 The page reports agents, task status, file locks, and handoffs for the selected project. It exposes no team or task write endpoints and is not a task execution or full orchestration platform. If the SQLite read fails, the API returns an explicit degraded/error status and the page shows that the status is unavailable instead of presenting an empty result as healthy.
 
+## Memory Map
+
+The Graph page is the single visual graph surface. It renders the deterministic,
+source-backed `GET /api/knowledge-graph` projection with Apache ECharts. The
+older Cytoscape/Dagre renderer is removed from the Dashboard, so an empty or
+failed Memory Map no longer silently falls back to a different graph model.
+
+`GET /api/graph` remains available as a backend compatibility route for MCP,
+CLI, scripts, and older clients. It is not the Dashboard's visual data source.
+
 ## Maintenance Workbench
 
 The Observations page exposes three explicit maintenance actions:

package/docs/DEVELOPMENT.md

@@ -13,8 +13,8 @@ Memorix is a TypeScript project built around:
 
 ## Current Development Baseline
 
-The current release work targets the **1.8.3 release line** and package metadata
-is kept at `1.8.3` for this release commit.
+The current release work targets the **1.8.5 release line** and package metadata
+is kept at `1.8.5` for this release commit.
 
 Contributors should assume the following areas are part of the current release line:
 

package/docs/DOCKER.md

@@ -1,6 +1,9 @@
 # Docker Deployment
 
-Memorix supports Docker as an **HTTP service deployment path**.
+Memorix supports Docker as a **VPS/hosted HTTP service deployment path**.
+
+Local development and verification should run the Node service directly. Do
+not start Docker Desktop or build a local image just to use Memorix.
 
 This Docker flow is for:
 
@@ -83,7 +86,7 @@ It is not a promise that stdio MCP magically becomes container-friendly.
 
 ## Important Path Truth
 
-Docker works best when Memorix can **see the repositories it is asked to bind**.
+VPS Docker works best when Memorix can **see the repositories it is asked to bind**.
 
 Project-scoped features such as:
 
@@ -97,7 +100,7 @@ depend on the HTTP service being able to access the repository path.
 
 ### Good fit
 
-- Docker Desktop on the same machine as your IDE
+- a VPS or hosted machine that can see the repositories it is asked to bind
 - a compose setup that mounts the repo you are working on into the container
 - `memorix_session_start(projectRoot=...)` using a path visible **inside** the container
 

package/docs/INTEGRATIONS.md

@@ -26,7 +26,7 @@ That command installs the recommended Memorix package or config for the target a
 | memcode | Opens a terminal coding agent that already uses Memorix memory | `memorix`, `memcode` |
 | HTTP service | Runs one shared MCP endpoint plus dashboard | `memorix background start` |
 
-HTTP is not required for normal agent setup. Use it when you intentionally want a shared background process, dashboard, Docker deployment, or multiple clients using the same MCP endpoint.
+HTTP is not required for normal agent setup. Use it when you intentionally want a shared background process, dashboard, VPS Docker deployment, or multiple clients using the same MCP endpoint. Local verification runs the Node service directly; Docker is not required on a developer machine.
 
 CLI, MCP, and HTTP have separate jobs:
 

package/docs/MODULES.md

@@ -1,18 +1,35 @@
 # Memorix 模块详解
 
-> 最后更新: 2026-08-14 (v1.4.3)
-> 本文档详细记录每个模块的实现细节、关键算法和注意事项
+> 最后更新: 2026-08-30（当前发布线 v1.8.5）
+> 本文档记录当前模块边界、关键算法和兼容层，不把历史实现误写成运行时主路径。
 
-> 本文档中的早期 JSON/Orama 章节保留为历史模块说明。当前运行时的
-> SQLite 数据层和长期记忆生命周期以 `docs/ARCHITECTURE.md`、
-> `docs/1.3-MEMORY-ARCHITECTURE.md` 及对应源码为准。
+> 当前真实主路径先看下面的模块总览，再看各模块的细节。早期 JSON/Orama
+> 说明仍保留用于迁移和实现背景，但不代表 JSON 是运行时主存储。
+
+## 当前模块总览
+
+| 模块 | 当前作用 | 是否主路径 |
+| --- | --- | --- |
+| `store/sqlite-db.ts`、`store/sqlite-store.ts` | 持久化观察、会话、图谱、知识、长期记忆、媒体和协作状态 | 是 |
+| `store/orama-store.ts` | 从 SQLite 数据重建的全文/向量检索索引 | 是，索引层 |
+| `memory/graph.ts` | MCP 兼容的实体/关系操作外观，底层写入 SQLite | 是 |
+| `wiki/knowledge-graph.ts` | Dashboard 的证据化 Memory Map 投影，不是真实数据源 | 是，展示层 |
+| `dashboard/static/` | 只保留 ECharts Memory Map 这一套图谱界面 | 是 |
+| `dashboard/server.ts`、`cli/commands/serve-http.ts` | 独立 Dashboard 与 HTTP 控制面两个宿主；按各自绑定范围读取同一套业务模块 | 是，宿主层 |
+| `store/persistence-json.ts`、`config/legacy-loader.ts` | 老版本数据和配置的迁移/兼容读取 | 兼容层 |
+
+本轮清扫移除了 Dashboard 旧的 Cytoscape/Dagre 图谱渲染器及其前端依赖。
+后端 `/api/graph` 和 MCP 图谱工具仍保留，因为外部脚本和客户端可能直接调用它们。
+两个 Dashboard 宿主也保留：standalone 用于本地只读浏览，HTTP 控制面负责带会话和
+项目绑定的服务。它们可以共享维护逻辑，但不能因为代码位置相似就把绑定边界合并。
 
 ---
 
-## 1. Orama 搜索引擎 (`store/orama-store.ts`)
+## 1. Orama 搜索索引 (`store/orama-store.ts`)
 
 ### 概述
-基于 [Orama](https://github.com/orama/orama) 的全文/混合搜索引擎，344行。
+基于 [Orama](https://github.com/orama/orama) 的全文/混合搜索索引。它不是持久化主库；
+启动或数据变化后可从 SQLite 观察记录重建。
 
 ### Schema 设计
 ```typescript
@@ -51,14 +68,22 @@ const schema = {
 
 ### ⚠️ 注意事项
 - Orama 的 where 子句在 `term: '' + number filter` 时可能不可靠，因此 `compactDetail` 使用内存查找而非 Orama 查询
-- 数据库是内存中的，重启后需要通过 `reindexObservations()` 重建
+- 索引是内存中的，重启后需要通过 `reindexObservations()` 从 SQLite 重建
 - `resetDb()` 用于热重载场景 — 先清空再重建
 
 ---
 
-## 2. 持久化层 (`store/persistence.ts`)
+## 2. 持久化层 (`store/sqlite-db.ts`, `store/sqlite-store.ts`, `store/persistence.ts`)
+
+### 当前主路径
+
+运行时使用 `~/.memorix/data/memorix.db` 这一 SQLite 数据库。观察记录、图谱、知识
+工作区、长期记忆、媒体、会话和协作状态共享同一数据库连接与迁移机制；`projectId`
+用于数据隔离，不再通过多个 JSON 子目录拼接运行时状态。
+
+### 历史 JSON/JSONL 兼容格式
 
-### 存储目录
+以下文件只用于旧版本迁移、显式导入导出或诊断，不是新写入的主路径。
 ```
 ~/.memorix/data/
 ├── observations.json      # 所有 observation 的 JSON 数组
@@ -76,16 +101,16 @@ const schema = {
 {"name":"port-config","entityType":"config","observations":["默认端口 3001"]}
 ```
 
-### 设计决策
-- **全局共享目录** (`~/.memorix/data/`): 让不同 Agent 看到同一份数据
-- **JSONL 而非单 JSON**: 与 MCP Official Memory Server 的格式兼容
-- **observations.json 用 JSON 而非 JSONL**: observation 结构更复杂，JSON 更方便整体读写
-- **ID 计数器单独文件**: 避免扫描所有 observation 来确定下一个 ID
+### 兼容设计
+- **全局共享目录** (`~/.memorix/data/`): 让不同 Agent 看到同一份 SQLite 数据
+- **JSONL**: 保留 MCP Official Memory Server 兼容和旧数据迁移能力
+- **observations.json**: 保留旧 observation 导入和显式导出能力
+- **SQLite 事务与文件锁**: 新写入由 SQLite 事务负责一致性，必要时仍使用文件锁保护跨进程操作
 
 ### ⚠️ 注意事项
-- v0.9.6 后所有数据存储在单一平坦目录 `~/.memorix/data/`，projectId 仅作为元数据
-- 有文件锁机制 (`store/file-lock.ts`) — 使用 `.memorix.lock` 目录锁 + 10s 超时检测
-- 热重载使用 `fs.watchFile` (polling) 监听 `observations.json` 变化
+- `store/persistence-json.ts` 是兼容模块，不要把它当成新的写入 API
+- `migrateSubdirsToFlat()` 只处理早期按项目分目录的数据
+- `store/obs-store.ts` 在 SQLite 不可用时会进入只读降级模式，不应偷偷回写 `observations.json`
 
 ---
 
@@ -105,12 +130,13 @@ const schema = {
 | `readGraph` | 返回完整图谱 |
 
 ### 持久化时机
-- 每次 CRUD 操作后立即写入磁盘
-- `init()` 时从磁盘加载
+- 每次 CRUD 操作后立即写入共享 SQLite 数据库
+- `init()` 时从 SQLite 加载
 
 ### ⚠️ 注意事项
 - `createEntities` 对同名实体是幂等的 — 不会覆盖已有观察
 - 关系的 `from` 和 `to` 必须引用已存在的实体名
+- JSONL 只属于兼容输入/输出；当前实体和关系由 SQLite `graph_entities`、`graph_relations` 表提供
 
 ---
 

package/docs/PERFORMANCE.md

@@ -57,7 +57,7 @@ On the release development machine used for this check, the healthy HTTP service
 
 ## What Can Be Heavier
 
-- `npm run build`, `npx vitest run`, and Docker image builds can use substantial CPU and disk while they run.
+- `npm run build` and `npx vitest run` can use substantial CPU and disk while they run. Local verification uses the sequential Node/npm build and does not require Docker; Docker image builds are reserved for the VPS/hosted deployment path.
 - Docker image size mostly comes from Node, npm dependencies, build artifacts, and image layers. The container runtime should be judged separately from image size.
 - Dashboard browsing can add browser-side memory and CPU outside the Memorix Node process.
 - Large imports, Git log ingestion, workspace sync, and skill generation can temporarily increase CPU and disk I/O.

package/docs/README.md

@@ -79,6 +79,7 @@ The public docs are organized by user intent:
 | System shape, data flows, memory layers | [ARCHITECTURE.md](ARCHITECTURE.md) |
 | Design decisions and rationale | [DESIGN_DECISIONS.md](DESIGN_DECISIONS.md) |
 | Module-by-module notes | [MODULES.md](MODULES.md) |
+| Current implementation status and ecosystem watch | [ACTIVE_WORK.md](../ACTIVE_WORK.md) |
 | CodeGraph Memory / Context Fabric design | [2026-06-29-codegraph-memory-context-fabric-design.md](superpowers/specs/2026-06-29-codegraph-memory-context-fabric-design.md) |
 | Auto Context Layer design | [2026-06-29-auto-context-layer-design.md](superpowers/specs/2026-06-29-auto-context-layer-design.md) |
 | 1.2 product direction and user journey | [1.2 Product Story](1.2.0-PRODUCT-STORY.md) |
@@ -94,7 +95,7 @@ The public docs are organized by user intent:
 | 1.2 honest Lite and optional semantic CodeGraph provider contract | [1.2 Provider Quality](1.2.0-PROVIDER-QUALITY.md) |
 | 1.3 long-term memory model, source boundary, and lifecycle | [1.3 Memory Architecture](1.3-MEMORY-ARCHITECTURE.md) |
 | Active context-control work | [1.2.2 Memory Control Plane](1.2.2-MEMORY-CONTROL-PLANE.md) |
-| 1.8.3 stdio discovery startup and compatibility acceptance contract | [1.8.0 Release Specification](1.8.0-RELEASE-CANDIDATE-SPEC.md) |
+| 1.8.5 MCP compatibility acceptance contract | [1.8.0 Release Specification](1.8.0-RELEASE-CANDIDATE-SPEC.md) |
 | Historical cloud sync and multi-agent research | [CLOUD_SYNC_AND_MULTI_AGENT_RESEARCH.md](CLOUD_SYNC_AND_MULTI_AGENT_RESEARCH.md) |
 | Known issues and old roadmap notes | [KNOWN_ISSUES_AND_ROADMAP.md](KNOWN_ISSUES_AND_ROADMAP.md) |
 
@@ -122,7 +123,7 @@ Historical/deep-reference documents may describe older designs. If they conflict
 
 ## Current Product Line
 
-The current product line is **1.8.3**. The authoritative acceptance contract is
+The current product line is **1.8.5**. The authoritative acceptance contract is
 [1.8.0 Release Specification](1.8.0-RELEASE-CANDIDATE-SPEC.md).
 The current baseline has:
 
@@ -141,13 +142,13 @@ The current baseline has:
 - `~/.memorix/config.toml` and project `memorix.toml` are the user-facing configuration model
 - legacy `memorix.yml`, `.env`, and `config.json` files are still read for compatibility, but new setups should use TOML
 
-For MCP compatibility, 1.8.3 preserves legacy 2025-era initialize and
+For MCP compatibility, 1.8.5 preserves legacy 2025-era initialize and
 stateful Streamable HTTP behavior. `memorix serve` starts a bounded stdio
 startup gate: pre-initialize 2026-07-28 `server/discover` is answered with a
 complete discovery result, and other early JSON-RPC messages replay in order
 through the pinned SDK transport. Versionless `tools/list` and `tools/call`
 continue through the SDK's legacy result envelopes. Modern result metadata is
-limited to the discovery response (`ttlMs: 0`, private cache scope); Tasks,
-subscriptions, and list-response caching are unsupported. Stateless HTTP
-project handles are a compatibility adapter, not a claim of complete 2026
-conformance.
+returned for discovery, list, and call responses. The official subscriptions
+listen surface is available. Durable Tasks remain explicitly unsupported, and
+list responses carry a private zero-TTL hint instead of a reusable server-side
+cache. Stateless HTTP project handles are supported on the modern path.

package/docs/SETUP.md

@@ -24,7 +24,7 @@ Common runtime entry points:
 | `memorix serve-http --port 3211` | foreground HTTP MCP for debugging or supervised launches |
 | `memorix` / `memcode` | bundled terminal agent that uses the same Memorix memory pool |
 
-Most users should start with `memorix setup --agent <agent> --global`. Use raw `memorix serve` only when you are wiring an MCP client manually. Use HTTP when you intentionally want one shared background process, browser dashboard, Docker deployment, or multiple clients using the same MCP endpoint. Use the CLI for manual operation and automation. Use memcode when you want the bundled terminal agent.
+Most users should start with `memorix setup --agent <agent> --global`. Use raw `memorix serve` only when you are wiring an MCP client manually. Use HTTP when you intentionally want one shared background process, browser dashboard, VPS Docker deployment, or multiple clients using the same MCP endpoint. Local development and verification run the Node service directly and do not require Docker. Use the CLI for manual operation and automation. Use memcode when you want the bundled terminal agent.
 
 For agent-specific plugin, rules, hooks, and skills support, see [INTEGRATIONS.md](INTEGRATIONS.md).
 
@@ -151,7 +151,7 @@ memorix serve
 
 Use this when your agent only needs a raw local stdio MCP process or you are debugging a manual config. The agent starts `memorix serve` and communicates with it over stdio.
 
-A bare `memorix serve` defaults to `--mode micro`, which exposes 9 high-signal tools so agent context is not crowded by rarely used schemas. Use `memorix serve --mode lite` for the extended solo memory surface, `--mode team` for coordination tools, or `--mode full` for advanced and MCP Memory compatibility tools.
+A bare `memorix serve` defaults to `--mode micro`, which exposes 9 high-signal tools so agent context is not crowded by rarely used schemas. Use `memorix serve --mode lite` for the 20-tool solo memory surface, `--mode team` for the 28-tool coordination surface, or `--mode full` for all 47 advanced and MCP Memory compatibility tools.
 
 `memorix setup` writes `--mode lite` into the installed MCP config: the generated guidance teaches the extended surface (sessions, timeline, reasoning, retention), so the installed server must actually expose it. Override with `MEMORIX_MODE` if you prefer a different profile.
 
@@ -216,7 +216,7 @@ This starts a local background service:
 - MCP endpoint: `http://localhost:3211/mcp`
 - health: `http://localhost:3211/health`
 
-HTTP mode is for a shared process. It is useful when multiple clients should connect to one Memorix endpoint, when you want the browser dashboard, or when running Memorix through Docker. It is not needed for the normal one-agent stdio MCP setup.
+HTTP mode is for a shared process. It is useful when multiple clients should connect to one Memorix endpoint, when you want the browser dashboard, or when running Memorix through Docker on a VPS/hosted machine. It is not needed for the normal one-agent stdio MCP setup.
 
 Companion commands: