NeuroDock Cognitive Graph

neurodock-mcp-cognitive-graph

NeuroDock 基础架构的持久实体记忆，通过 MCP 服务提供。将用户关于人员、 项目、决策和概念的工作记忆外化，让注意力高度集中或上下文切换后的会话 不必从零开始。

这是 v0.0.3——当前版本。向量检索、fastembed 嵌入和 sqlite-vec 推迟到未来版本；请参阅 CHANGELOG.md。

安装

uv add neurodock-mcp-cognitive-graph
# or
pip install neurodock-mcp-cognitive-graph

用作 MCP 服务

将以下内容添加到 ~/.claude.json（Claude Code）或 claude_desktop_config.json（Claude Desktop）：

{
  "mcpServers": {
    "neurodock-cognitive-graph": {
      "command": "uv",
      "args": ["run", "neurodock-mcp-cognitive-graph"]
    }
  }
}

快速入门

# From the workspace root.
uv sync --all-packages

# Start the server on stdio (Claude Desktop / Claude Code MCP config).
uv run neurodock-mcp-cognitive-graph

默认情况下，服务将图谱存储在 ~/.neurodock/cognitive-graph.sqlite。 使用 NEURODOCK_GRAPH_DB_PATH 环境变量可覆盖此路径。

工具（v0.0.3）

工具	用途
recall_entity(name_or_alias)	查找人员／项目／决策／概念。返回实体、其事实（上限为 500 条）、一级邻居（上限为 20 个）以及解析诊断信息。
record_fact(subject, predicate, object, source?, confidence?)	持久化一条带类型边的事实。按 (type, name) 自动创建实体。强制使用 v0.1.0 的八种谓词词汇。
recall_decisions(project, since?)	返回某个项目的决策，按日期降序排列，上限为 200 条。
weekly_rollup(project?)	由服务端模板生成过去七个 UTC 日的活动摘要。不调用大模型（供应商边界）。

完整的输入／输出约定见 schemas/。src/neurodock_mcp_cognitive_graph/types.py 中的 Pydantic v2 模型与这些架构保持一致。

谓词词汇

v0.1.0 的八种谓词为：mentioned_in、decided_in、 reports_to、depends_on、resolved_by、blocked_by、tagged、 belongs_to。未知谓词会触发 PREDICATE_NOT_IN_VOCABULARY。 扩展谓词通过 v0.2 的 type_extensions 机制引入——请参阅 ADR 0002 — cognitive-graph 工具设计。

隐私

• 本地优先。无法访问网络。无遥测。
• source 字符串按原样存储，服务绝不会获取这些字符串的内容。
• 用户内容（实体名称、决策标题、事实文本）绝不会记录到日志中。 错误日志只包含结构化错误代码。

存储

SQLite。单个文件。迁移以编号 .sql 文件的形式存放在 src/neurodock_mcp_cognitive_graph/migrations/ 中，并在首次连接时 应用。架构定义见 migrations/0001_init.sql。

架构

src/neurodock_mcp_cognitive_graph/
├── server.py            FastMCP wiring + CLI entrypoint
├── types.py             Pydantic v2 models (mirror of the JSON Schemas)
├── config.py            Resolves the SQLite path
├── clock.py             SystemClock / FixedClock
├── errors.py            ToolError envelope
├── resolution.py        Entity name/alias cascade (exact, alias only in v0.0.3)
├── rollup.py            Heuristic decision/blocker/next-action assembly
├── storage/
│   ├── base.py          Storage Protocol + row dataclasses
│   ├── memory.py        InMemoryStorage (used by tests)
│   └── sqlite.py        SQLiteStorage (production backing)
├── tools/
│   ├── recall_entity.py
│   ├── record_fact.py
│   ├── recall_decisions.py
│   └── weekly_rollup.py
└── migrations/
    └── 0001_init.sql

ADR 参考

• ADR 0002 — cognitive-graph 工具设计 — 设计依据、词汇、输出格式，以及 CHANGELOG.md 中记录的三个未决问题 在 v0.0.3 中的解决方案。
• ADR 0001 — chronometric 工具设计 — 本软件包沿用的跨领域先例（带偏移量的 ISO 8601、用于粗粒度信号的枚举、 结构化错误）。

测试

uv run pytest packages/mcp-cognitive-graph/tests/ -v

25 项测试，涵盖：每个工具的单元测试、一个 FastMCP 协议一致性测试套件（用于测试每个工具，并使用 jsonschema 根据 JSON Schema 验证响应），以及一个针对真实文件存储 SQLite 数据库运行的端到端测试。