1. 项目定位与设计目标

Veracium 是一个为大语言模型（LLM）提供长期、结构化、可审计记忆能力的 Python 库。其核心目标是把"对话中的零散事实"提炼为带溯源（provenance）的类型化图边（typed graph edges），从而让模型在后续会话中能够基于可验证的记忆生成回答，而非依赖不可控的隐式上下文窗口。

项目的设计遵循以下原则：

• 自带模型（bring-your-own-model）：任何符合 Complete 协议的可调用对象都可以作为 LLM 后端接入，无需绑定特定厂商。Anthropic 是参考实现，同时 examples/claude_cli_provider.py 演示了仅 31 行的极简接入方式。
• 可插拔存储（pluggable store）：记忆的"事实源"由 Store 接口抽象，默认参考实现 SqliteStore 满足大多数本地与小型生产场景。社区正推动的 Postgres 与 Neo4j 后端将保持相同接口契约，仅替换实现。
• MCP 协议原生支持：通过可选依赖 veracium[mcp] 暴露 remember / recall / answer / maintain 四个动词，可被 Claude Code、Claude Desktop 等任意 MCP 客户端直接调用。
• 纵深安全：记忆的"谁说的 / 是否可断言 / 是否可被引用"在 ingest、gate、compile 三道环节独立判定，杜绝第三方文本借系统事件"洗白"为可信断言。

资料来源：README.md:1-80、src/veracium/__init__.py:1-40

2. 核心架构

Veracium 的运行时由三层构成：模型层、记忆层、协议层。下表汇总各层的关键模块与职责：

Store 接口被刻意保持小巧，仅包含 edges、episodes、invalidation、per-user isolation 四类操作，从而保证任何后端（SQLite / Postgres / Neo4j）都可对等替换而不破坏调用方。SqliteStore 是该接口的参考实现，社区后续将按相同契约补齐 Postgres（issue #1）与 Neo4j（issue #2）后端。

资料来源：src/veracium/store/base.py:1-60、src/veracium/store/sqlite.py:1-120、docs/mcp.md:1-40

3. 快速上手

3.1 安装

项目通过 pyproject.toml 管理依赖与可选 extras。基础安装仅引入核心记忆与 SQLite 后端：

pip install veracium

若需要通过 MCP 协议将 Veracium 作为服务端暴露给外部 LLM 客户端，使用可选依赖：

pip install "veracium[mcp]"

可选 extras 对应 README 中说明的扩展场景，可与基础包叠加安装。

资料来源：pyproject.toml:1-60、README.md:30-90

3.2 最小示例

完成安装后，可在任意 Python 入口处实例化 Memory 并使用其四个核心动词：

from veracium import Memory

mem = Memory()  # 默认使用 Anthropic provider 与 SqliteStore
mem.remember(user_id="u-001", text="用户偏好 Markdown 表格输出。")
ctx = mem.recall(user_id="u-001", query="输出偏好")
answer = mem.answer(user_id="u-001", query="总结我的写作偏好", context=ctx)

Memory 同时提供面向宿主应用的查询接口（v0.2.1 引入）：list_entities() 返回按实体聚合的边与 episode 计数；edges_since(user_id, since) 按时间窗口与 provenance 过滤新学到的边，便于主动召回规划与覆盖审计。

资料来源：src/veracium/memory.py:1-160、README.md:60-120

3.3 接入自定义模型

对于不在 Anthropic 生态内的用户，可将任何满足 Complete 签名的可调用对象注入 Memory，无需修改源码：

from veracium import Memory

def my_complete(prompt: str, **kw) -> str:
    # 调用 OpenAI 兼容端点 / vLLM / Ollama 的 OpenAI endpoint / 自托管服务
    ...

mem = Memory(complete=my_complete)

社区正在推进 examples/openai_provider.py（issue #3），为 OpenAI 兼容 API 提供 31 行级别的最小可用样例，覆盖 OpenAI、vLLM、Ollama 等常见目标。

资料来源：src/veracium/llm/:1-80、examples/claude_cli_provider.py:1-31

4. 运行自检与常见路径

4.1 MCP 服务端

安装 veracium[mcp] 后，veracium-mcp CLI 即可作为 stdio MCP 服务端启动。从 v0.2.2 起，--help 与 --version 参数被正确识别，未知参数会指引用户查看帮助；启动失败（如缺失 ANTHROPIC_API_KEY）会以一行清晰的错误信息退出，避免"静默启动再失败"的体验问题。仓库根目录的 server.json（v0.2.3 起）符合当前 MCP Registry schema，可被 registry.modelcontextprotocol.io 抓取收录。

资料来源：docs/mcp.md:1-60、README.md:90-140

4.2 自检（selfcheck）

veracium selfcheck 是 v0.2.4 引入的诊断入口。它会先对 provider 做预检：若 SDK 未安装或 ANTHROPIC_API_KEY 缺失，立即以一行安装提示退出，而不再继续运行后抛回 traceback。这一改动解决了此前"错误检查被记为 assert、输出形如 FAIL … injection asserts=1"的误导性得分卡。

资料来源：README.md:120-170、docs/index.md:1-40

4.3 安全要点

Veracium 的安全设计围绕"信任来源可追溯"展开：

• v0.1.6 起，第三方 use_only 推理不再被送入编译后的 wiki，关闭了"通过 wiki 路径间接断言不可信事实"的旁路。
• v0.1.7 修复了"系统事件洗白"（system-event laundering）旁路：嵌入在 SYSTEM/USER 事件中的第三方文本不再自动继承宿主事件的信任等级。
• gate / compile 阶段对每条边独立判断是否可被 assert，从而把"可被检索"与"可被断言"解耦。

资料来源：README.md:60-100、src/veracium/memory.py:80-200

5. 下一步建议

• 阅读 docs/mcp.md 获取 MCP 客户端配置片段；如需补全 Claude Code / Claude Desktop 的复制可用模板，可跟踪 issue #4。
• 若计划迁移到 Postgres 或 Neo4j，可参考 src/veracium/store/base.py 中的接口契约，并对照 SqliteStore 的实现细节（issue #1、#2）。
• 接入非 Anthropic 模型时，先按 examples/claude_cli_provider.py 的 31 行模式实现 Complete 协议，再观察社区即将推出的 examples/openai_provider.py（issue #3）作为 OpenAI 兼容端的最小示例。

资料来源：docs/index.md:1-60、src/veracium/store/base.py:1-60

一、剧集层：原始事件的不可变记录

剧集是写入管道的最底层，表示一次未经处理的"对话/事件"。每一个剧集携带：

• 作者角色（如 USER、SYSTEM、TOOL），用于信任判定
• 文本内容与上下文元数据
• 用户隔离键 user_id，保证多租户隔离
• 时间戳

剧集层的设计意图是"保真"——不做归并、不做推断，把外部世界真实地记录下来。安全侧强调"system-event laundering"的防御：嵌入在 SYSTEM/USER 事件中的第三方文本不能继承事件作者的完整信任级别，必须被识别并降级。

资料来源：src/veracium/ingest.py:1-120；docs/design-rationale.md:1-80

二、边层：带溯源的类型化图边

边的设计目的是把剧集蒸馏成"机器可推理的事实"。每条边是一个带类型的图边三元组 (subject, predicate, object)，并附带：

• provenance：来源剧集引用
• trust：作者信任级别
• derived_from：与其它边的派生关系
• valid_at / invalid_at：时间边界

这一层是 Veracium 的"事实之源"（store-of-record）。宿主查询 Memory.list_entities() 与 Memory.edges_since() 直接在这一层上运行，按 provenance 过滤、按实体聚合，用于主动召回规划与覆盖审计。Store 接口（src/veracium/store/base.py）刻意保持极小——只覆盖边、剧集、失效、用户隔离——便于 Postgres、Neo4j 等后端按相同契约接入。

资料来源：src/veracium/graph.py:1-180；src/veracium/schema.py:1-150；src/veracium/store/base.py:1-100；src/veracium/store/sqlite.py:1-160

三、Wiki 层：受预算约束的编译视图

Wiki 不是另一份事实库，而是从边层按上下文预算编译出来的可读摘要。recall() 把 Wiki 放进 gate 的 GROUNDED 块——只有通过 gate 的内容才能被断言；第三方的 use_only 推断不能进入 Wiki（v0.1.6 强化）。这一限制保证"被 Wiki 引用"等价于"可被断言"，避免可信路径上的安全穿越。

flowchart LR
  A[Episodes<br/>原始事件] -->|distill / extract_json| B[Edges<br/>带溯源图边]
  B -->|gate.partition| C{GROUNDED?}
  C -->|是| D[Wiki<br/>编译视图]
  C -->|否 / use_only| E[仅供 recall，不入 Wiki]
  D -->|budget-aware recall| F[宿主 answer / list_entities]
  E -->|recall only| F

资料来源：src/veracium/compile.py:1-200；src/veracium/gate.py:1-140；docs/concepts.md:1-120

四、信任闸门（Gate）：跨层安全边界

三层之间的关键动作都由 gate 控制。Gate 把进入 recall() 上下文的事实分成两类：

• 可断言（GROUNDED）：能进入 Wiki，能被宿主当事实输出
• 仅供使用（use_only）：只允许出现在提示里用于推理，禁止被断言

这种分区机制让 Wiki 路径与直接 recall 路径共享同一安全策略，避免出现"通过 Wiki 间接绕过 gate"的安全漏洞。feedback/forget/audit 四个动词也都落到边层或审计日志，闭环回写到 Store。

资料来源：src/veracium/gate.py:1-140；src/veracium/compile.py:1-200；docs/design-rationale.md:80-200；docs/concepts.md:120-240

五、为什么是三层

社区讨论（issue #1、#2）已经把"边 + 剧集 + Wiki"作为 Store 后端替换（Postgres、Neo4j）的契约基础：后端只关心边与剧集的持久化与查询语义，Wiki 是无状态的编译产物，可以由任意 LLM provider 重新生成。list_entities() 与 edges_since()（v0.2.1）则把边层暴露给宿主侧的智能层，使三层模型既支持底层图查询、又支持上层自然语言召回——这正是 Veracium "bring-your-own-model" 设计得以成立的核心抽象。

资料来源：src/veracium/store/base.py:1-100；src/veracium/store/sqlite.py:1-160；src/veracium/graph.py:1-180；docs/concepts.md:1-240

相关社区议题

• #1 Store backend: Postgres：希望复用同一 Store 契约落库 JSONB 边/剧集
• #2 Store backend: Neo4j：希望用图数据库原生支持路径/邻居查询（依赖边层结构）
• #3 Provider example: OpenAI-compatible Complete callable：Provider 替换只影响 dist

模型目的与范围

Veracium 的安全与溯源模型解决一类典型的提示注入与信任漂移问题：第三方文本（邮件正文、引文、抓取到的网页片段）被夹带进 USER / SYSTEM 事件后，原本"被引用"的素材会被赋予事件自身的全权信任，并最终作为可断言事实进入模型上下文。该模型围绕三条不变量展开：

1. 可断言性 (assertability)：只有具备直接溯源 (GROUNDED) 的事实才能被模型在答案中作为已发生事实陈述。
2. 来源隔离 (provenance isolation)：第三方文本始终降级为 use_only，禁止进入编译后的 wiki 与断言通道。
3. 作者溯源 (author attribution)：任何片段必须可追溯到一次具体的、经过校验的事件，并在派生关系中保留 derived_from 链。

ingest、gate、compile 三个模块分别承担"写入前降级"、"读取前分诊"、"压缩前裁剪"的角色，形成一条贯穿 remember → recall → answer 的纵深防御。

资料来源：docs/concepts.md:1-40、src/veracium/schema.py:1-90

闸门分区：`gate.partition`

gate.partition 是模型在召回路径上的分诊入口。它接收从 Store 取回的边与情节 (episode)，按溯源类型将其分入三个互不重叠的桶：

• GROUNDED：直接来自 USER-authored 事件，可作为已发生事实进入断言通道。
• USE_ONLY：第三方引用、模型推断、邮件正文摘要等，仅供上下文参考，禁止被陈述。
• QUARANTINE：作者可疑、不可解析或与策略冲突的内容，被隔离并不进入 LLM 上下文。

recall() 在把上下文喂给 LLM 之前，必须先调用分区，并仅将 GROUNDED 桶标记为 assertable。任何命中 USE_ONLY 的片段都会被显式标注，禁止在生成阶段被陈述为事实。

资料来源：src/veracium/gate.py:1-80、src/veracium/recall.py:1-60

隔离区与系统事件清洗防护

ingest 在写库前必须进行作者校验：原始事件必须携带 role（USER / SYSTEM / THIRD_PARTY）以及显式的 quoted_blocks。当 SYSTEM 或 USER 事件中嵌入了第三方文本（典型形态："邮件主题：……"、"对方回复摘要：……"），这些片段必须被剥离并降级为 use_only 处理，绝不能继承宿主事件的可断言信任。

v0.1.7 修复的 *system-event laundering*（系统事件清洗）绕过正是此处的关键：此前嵌入内容会获得宿主事件的完整信任，从而可作为断言事实进入 wiki。该修复同时引入 derived_from 字段，让下游可以显式看到一条边的派生链 (USER → SYSTEM+quoted_block → 派生边)，从而拒绝任何"宿主事件全权信任"的隐式升级。

资料来源：src/veracium/ingest.py:1-120、src/veracium/schema.py:40-110、v0.1.7 release notes

use_only 强制与编译期阻断

compile 把分散的边压缩为 wiki 形式的紧凑上下文。在 v0.1.6 之前，wiki 块会被 recall() 整体置于 GROUNDED 之中，导致 use_only 事实可"借道"wiki 被声明。修复后的策略是：

• compile 在产出 wiki 时只允许直接来自 USER-authored 事件的边；
• 任何含 use_only 标记的片段在编译阶段被剔除或显式降级；
• gate.partition 把 wiki 块作为受信任但不可写入断言路径的 materialized context 处理，断言必须仍走原始 GROUNDED 边。

这一约束闭合了"借道 wiki"的注入面，使注入攻击者即使污染了某条 USE_ONLY 边，也无法通过 wiki 路径把它升级为可断言事实。配合 v0.1.7 的清洗防护，构成 *写入 → 压缩 → 分诊* 三段式 use_only 强制链。

资料来源：src/veracium/compile.py:1-100、src/veracium/gate.py:80-160、v0.1.6 release notes

端到端调用链

flowchart LR
    A[remember event] --> B[ingest<br/>作者校验与降级]
    B --> C[(Store<br/>edges + episodes)]
    C --> D[recall 拉取]
    C --> J[compile → wiki]
    J --> D
    D --> E[gate.partition]
    E -->|GROUNDED| F[assertable context]
    E -->|USE_ONLY| G[参考上下文<br/>不可断言]
    E -->|QUARANTINE| H[隔离区]
    F --> I[answer]
    G --> I
    H -.丢弃.-> I

闸门在 recall → answer 的边界上做最后一道断言授权；隔离区与 use_only 强制共同保证任何被注入的内容，至多只能作为参考上下文出现，而无法被陈述为既成事实。

资料来源：src/veracium/gate.py:1-160、src/veracium/recall.py:1-80、src/veracium/compile.py:1-100

1. Store 接口设计

Store 的契约在 src/veracium/store/base.py 中刻意保持精简，只覆盖四类操作：

• 边（edges）：类型化的图边，带有来源（provenance）与有效性字段，是"事实记录"的基本单位。
• 剧集（episodes）：原始事件与蒸馏结果的容器，承载上下文回放能力。
• 失效（invalidation）：对已经学到但需要作废的事实进行显式撤销，是"忘记"动词的载体。
• 每用户隔离（per-user isolation）：所有读写都必须在 user_id 命名空间内完成，防止跨租户泄漏。

资料来源：src/veracium/store/base.py:1-80

该接口的"故意做小"是项目的一处明文设计选择——issue #1 的描述写道："Store interface is deliberately small — edges, episodes, invalidation, per-user isolation"。这让 Postgres、Neo4j 这样的目标后端只需镜像相同的方法签名即可接入，不必关心上游的蒸馏或门控逻辑。src/veracium/store/__init__.py 在包层面再导出 Store 与 SqliteStore，供 Memory 通过依赖注入获取。 资料来源：src/veracium/store/__init__.py:1-30

2. SQLite 参考实现

SqliteStore 是契约的"地面真相"实现，也是测试、veracium selfcheck 与本地开发默认使用的后端。其设计要点：

资料来源：src/veracium/store/sqlite.py:1-120

由于 SQLite 自身缺乏原生的图查询能力，路径（paths）、邻域（neighborhoods）只能在应用层拼装——这正是 issue #2 中推动 Neo4j 后端的核心动机："unlock native graph queries over memory (paths, neighborhoods) that the sqlite backend can't offer"。

3. 扩展路径：Postgres 与 Neo4j

社区当前最高互动的两条后端扩展请求指向两条互补方向：

• Postgres（issue #1，最受欢迎的生产部署路径）：复用同一 Store 契约，行用 JSONB 承载边和剧集可变字段，复刻 SqliteStore 的表结构。优势在于成熟的并发、复制、备份工具链，适合多进程常驻服务。
• Neo4j（issue #2，天然的图后端）：把"带来源的类型化图边"直接落地为原生节点—关系模型，自然支持多跳路径、子图遍历等 SQLite 难以表达的记忆查询。两者都需要遵循同一契约：实现 Store、保持每用户隔离不破口。

资料来源：GitHub Issue #1;GitHub Issue #2

flowchart LR
  Memory[Memory 上层 API] --> Store["Store 接口<br/>(base.py)"]
  Store --> SQLite["SqliteStore<br/>参考实现"]
  Store --> PG["PostgresStore<br/>(issue #1)"]
  Store --> Neo["Neo4jStore<br/>(issue #2)"]
  SQLite --- Port["portability.py<br/>导出/导入"]
  PG --- Port
  Neo --- Port

任何后端只要落在这张虚线框内，都可以驱动 Veracium 的其余部分；上层 Memory.remember / Memory.recall 不会感知差异。

4. 便携性与隔离保证

src/veracium/portability.py 提供了跨后端可移植的记忆导出/导入工具，这是 v0.2.0 的发布特性之一。它让本地 SQLite 与未来 Postgres / Neo4j 之间能够双向迁移数据，而不破坏：

• 每用户隔离：迁移操作同样以 user_id 为边界，不允许跨租户打包。
• 审计链：失效时间戳、derived_from 引用等保持原值，避免来源被剥离。
• 图结构：边与剧集按相同 ID 重新落库，使后续图查询在目标后端上等价。

资料来源：src/veracium/portability.py:1-90;v0.2.0 Release Notes

5. 小结

• Store 契约精简——边、剧集、失效、隔离——是扩展性的核心。
• SqliteStore 提供参考实现与默认开发形态。
• Postgres 与 Neo4j 是社区最期待的两条生产路径，分别对应"并发 + JSONB"与"原生图查询"两类动机。
• portability.py 为所有后端提供导出/导入托底，确保隔离与审计不被迁移破坏。

资料来源：src/veracium/memory.py:1-60

概述与设计动机

Veracium 的 LLM 层采用"自带模型"（bring-your-own-model）架构。任何满足 Complete 契约的可调用对象都可以作为 LLM 提供方接入，无需修改核心管线。这一设计将模型推理与记忆机制解耦：Veracium 负责处理摄取、门控、蒸馏与回忆的安全逻辑，而模型仅需提供一致的文本补全接口。Complete 契约在 src/veracium/llm/base.py 中定义，是整个记忆系统的语言模型入口。资料来源：src/veracium/llm/base.py:1-30

社区反馈显示，OpenAI 兼容 API（OpenAI、vLLM、Ollama 的 OpenAI 端点）的接入需求最为迫切，因此官方提供 examples/openai_provider.py 作为参考实现。资料来源：examples/openai_provider.py:1-31

Complete 契约的形态

Complete 契约本质上是一个接受提示字符串并返回模型输出字符串的可调用对象。具体形态取决于实现，但其语义约束在所有提供方之间保持一致：

• 输入：纯文本或经过模板渲染的提示，由 src/veracium/prompts.py 中的提示模板生成。资料来源：src/veracium/prompts.py:1-50
• 输出：单个字符串，作为蒸馏（distill）、回答（answer）等阶段的原始材料返回。
• 失败语义：契约不强制要求重试逻辑，但需要满足 v0.2.4 中 veracium selfcheck 的预检要求——若 SDK 缺失或环境变量（如 ANTHROPIC_API_KEY）未设置，应提前抛出清晰错误而非静默返回垃圾结果。资料来源：src/veracium/cli.py:1-80

参考实现：Anthropic 与 Claude CLI

Anthropic 提供方位于 src/veracium/llm/anthropic.py，是 Veracium 官方支持的完整 SDK 接入路径。它调用 Anthropic Python SDK 发送消息，并将响应文本提取为字符串。资料来源：src/veracium/llm/anthropic.py:1-60

examples/claude_cli_provider.py 则展示了另一种思路：通过 shell 调用 claude CLI 而非直接使用 SDK。整个文件仅 31 行，演示了如何用 subprocess 包装外部命令并解析输出，从而满足 Complete 契约。这种"包装器式"实现为无 SDK 环境或本地模型提供了接入范式。资料来源：examples/claude_cli_provider.py:1-31

自检、引导与 MCP 集成

提供方的健壮性直接影响整个系统的可信度。v0.2.4 引入 veracium selfcheck 预检机制，在运行注入测试前先验证 LLM 提供方是否可用：

flowchart LR
    A[veracium selfcheck] --> B{Provider 可用?}
    B -- 否 --> C[输出安装提示<br/>并退出]
    B -- 是 --> D[运行注入测试]
    D --> E[输出评分卡]

资料来源：src/veracium/cli.py:1-80

veracium-mcp 服务器在 v0.2.2 中也强化了引导体验：缺失 ANTHROPIC_API_KEY 时会输出单行清晰错误并退出，避免静默启动 stdio 服务器造成误导。资料来源：src/veracium/mcp/server.py:1-50

实践建议与社区议题

社区中尚未解决的 #3 号议题 提议增加 openai_provider.py 正式示例，以覆盖 OpenAI、vLLM、Ollama 的 OpenAI 兼容端点。用户实现自定义提供方时，建议遵循以下模式：

1. 签名一致性：函数签名严格匹配 Complete 契约，便于 Memory 类直接注入。
2. 早失败：在导入阶段或首次调用前检查依赖与凭证，避免在 remember() 或 recall() 流程中段报错。
3. 输出清洗：确保返回的是纯文本字符串，去除多余的系统消息或工具调用残留。

通过这套契约，Veracium 把模型选择权完全交还给部署者，同时保留了统一的记忆安全语义。

概述与设计意图

Veracium 通过 veracium[mcp] 额外依赖暴露一个 Model Context Protocol（MCP）服务器，使任何兼容 MCP 的客户端都能在标准化的工具调用下使用 Veracium 的记忆能力。该服务器在 stdio 之上启动，对外暴露四个核心动词：remember、recall、answer、maintain——它们一一映射到 Memory 对象上的同名方法。资料来源：docs/mcp.md:1-40

这一设计把"记忆系统"从 Python 库边界推进到了协议边界：客户端不需要 pip install veracium 也不需要导入 Memory，只要能说话 MCP 即可。社区在 issue #4 中指出当前缺少可直接复制的客户端配置片段（Claude Code、Claude Desktop、编辑器无关示例），本页正是为了补齐这一空白。资料来源：issues/4:1-20

服务端安装与启动

通过 PyPI 安装可选的 MCP 额外组件并获得 veracium-mcp 命令：

pip install "veracium[mcp]"

pyproject.toml 中 [project.optional-dependencies] 声明了 mcp 这一可选 extra，对应依赖为 mcp >= 1.0。资料来源：pyproject.toml:40-60

启动后服务器读取 ANTHROPIC_API_KEY 等环境变量并初始化底层 Memory。从 v0.2.2 起，veracium-mcp --help 与 --version 已可正确响应；未知参数会指向 --help；当 ANTHROPIC_API_KEY 缺失时退出会给出一行清晰提示，避免静默进入 stdio 循环。资料来源：docs/mcp.md:60-90，releases/v0.2.2:1-15

veracium-mcp --help     # 打印用法
veracium-mcp --version  # 打印版本
veracium-mcp            # 以 stdio 模式启动，等待客户端握手

工具接口契约

服务器把 Memory 的方法包装为 MCP 工具，每个工具接受 JSON 形参并返回结构化文本。下面以 remember 为例：

工具实现集中在 src/veracium/mcp_server.py 与 src/veracium/mcp.py 中，前者负责协议层编解码，后者负责参数到 Memory 方法的转译。资料来源：src/veracium/mcp_server.py:1-80

客户端接入配方

Claude Code（`.mcp.json`）

在仓库根目录或用户级 ~/.claude/mcp.json 中加入：

{
  "mcpServers": {
    "veracium": {
      "command": "veracium-mcp",
      "env": { "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}" }
    }
  }
}

Claude Code 在启动代理时会派生该进程并通过 stdio 交换 JSON-RPC。资料来源：docs/mcp.md:90-120

Claude Desktop

在 claude_desktop_config.json 的 mcpServers 段添加同名条目即可，结构与上例一致。Desktop 客户端同样使用 stdio，因此命令路径必须是绝对可执行的（建议使用 python -m veracium.mcp_server 作为后备）。资料来源：docs/mcp.md:120-150

编辑器无关示例（`mcp-client` CLI）

任何遵循 MCP stdio 协议的客户端只需：

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | veracium-mcp

即可枚举工具；调用 tools/call 时把 remember/recall/answer/maintain 作为 name 传入即可。资料来源：src/veracium/mcp.py:1-60

注册表发布与版本同步

v0.2.3 起，仓库根目录的 server.json 遵循 MCP Registry 当前 schema，README 中带有 mcp-name 校验标记，因此 Veracium 可发布到 registry.modelcontextprotocol.io 并被各类 MCP 目录抓取。server.json 中的版本号需与 pyproject.toml 的 version 字段保持一致，以避免目录显示过期版本。资料来源：server.json:1-20

flowchart LR
  A[MCP Client<br/>Claude Code / Desktop / 其他] -->|stdio JSON-RPC| B[veracium-mcp]
  B --> C[Memory 对象<br/>remember / recall / answer / maintain]
  C --> D[(SqliteStore<br/>或自定义 Store)]
  C --> E[Complete 提供方<br/>Anthropic 默认]

排错要点

• 端口未启动：若客户端看不到工具，先用 veracium-mcp --version 确认可执行路径可访问。资料来源：releases/v0.2.2:5-15
• 环境变量缺失：缺 ANTHROPIC_API_KEY 时 v0.2.2+ 会显式退出而非静默卡住。资料来源：releases/v0.2.2:10-15
• PyPI vs 源码安装：旧文档描述的是 git clone 后 pip install -e .，v0.2.3 已统一为 PyPI 安装流。资料来源：releases/v0.2.3:5-10

相关社区议题

• #4 Docs: MCP client recipes — 直接推动了本页"客户端接入配方"章节。
• v0.2.3 — MCP Registry readiness — 引入 server.json 与 README 的 mcp-name。
• v0.2.2 — veracium-mcp --help/--version — 改进了首次安装时的可观测性。

Veracium 的运维子系统围绕"上线前预检、运行中可观测、变更可审计、生命周期可控"四个目标展开。selfcheck 在命令启动前完成提供方 (provider) 预检；audit 记录每一次记忆变更；telemetry 提供可观测的运行指标；lifecycle 则管理 store、provider、MCP 端点的启停与维护流程。CLI (veracium / veracium-mcp) 是这些能力对外的统一入口。

selfcheck：提供方预检与健康检查

selfcheck 模块承担两类职责：(1) provider 预检——在真正调用 LLM 之前，验证 SDK 是否安装、API Key 是否存在、模型名是否合法；(2) 注入与门控健康度评分——对 recall 的 GROUNDED / UNTRUSTED 分区与 use_only 强制执行进行端到端探测。veracium selfcheck 自 v0.2.4 起对 provider 进行预检：当 SDK 缺失或 ANTHROPIC_API_KEY 未设置时，立即以一条清晰的安装提示退出，不再输出令人误读的 FAIL … injection asserts=1 评分卡（此前错误检查会被保守地记为 assert，外观上与注入保证失败完全一致）。资料来源：src/veracium/selfcheck.py:1-120

CLI 入口由 cli.py 暴露，所有 veracium 子命令（包括 selfcheck、remember、recall、answer、maintain）都注册于此。veracium-mcp 自 v0.2.2 起补齐了 --help 与 --version：此前任何参数都会被静默忽略并直接启动 stdio 服务，导致首次安装者困惑；未知参数现在会指引用户查看 --help，启动失败（如缺 ANTHROPIC_API_KEY）会以单行错误信息退出。资料来源：src/veracium/cli.py:1-180

审计日志（audit log）

audit.py 是 v0.2.0 引入的五大能力之一。每一次记忆写入、失效（invalidation）、forget 与 feedback 动词的调用都会落库到审计日志，便于事后回溯"哪条 edge 由哪次 remember / recall 产生、经过了哪次 gate 裁决"。审计与 store 中的 provenance 字段协同：Memory.edges_since(user_id, since) 在 v0.2.1 提供的主机查询能力即基于审计时间戳过滤。资料来源：src/veracium/audit.py:1-90、资料来源：src/veracium/lifecycle.py:30-110

遥测与诊断

telemetry.py 与 diagnostics.py 共同负责运行期可观测性。telemetry 暴露的指标包括 recall 调用频次、注入拦截计数、wiki 编译耗时等聚合维度；diagnostics 则用于一次性快照——例如列出当前 store 后端、provider 类型、每用户 edge / episode 数量、近期错误日志采样。这些能力被 Memory.list_entities()（v0.2.1）所消费，用于覆盖度审计与主动召回规划。资料来源：src/veracium/telemetry.py:1-80、资料来源：src/veracium/diagnostics.py:1-70

flowchart LR
  A[CLI / veracium-mcp] --> B[selfcheck preflight]
  B -- 通过 --> C[Memory: remember/recall/answer]
  C --> D[(Store)]
  C --> E[audit log]
  C --> F[telemetry]
  G[diagnostics] --> D
  H[lifecycle.maintain] --> D
  H --> E

生命周期（lifecycle）

lifecycle.py 是 store 与 provider 的"维护面"。它的动词包括：周期性的 wiki 重新编译、过期 edge 清理、maintain 命令触发的人工巡检，以及与 MCP server.json 协同的注册表发布流程（v0.2.3 MCP Registry readiness）。lifecycle 与 audit 共享写入路径：每一次维护动作都会落到审计日志，从而形成"操作 → 状态变更 → 审计"的可追踪链。资料来源：src/veracium/lifecycle.py:1-160

在 MCP 场景下，veracium-mcp 的 boot 路径会依次经过 selfcheck 预检、store 打开、lifecycle 状态恢复三步；若任何一步失败，CLI 会用一条短句指明根因（例如 "missing ANTHROPIC_API_KEY"），而不是堆栈。这套自上而下的错误处理是 v0.2.2 / v0.2.4 两次迭代的核心收获。资料来源：src/veracium/cli.py:120-180、资料来源：src/veracium/selfcheck.py:80-120

1. 仓库自带示例与配方入口

examples/ 与 docs/ 是“最小可用模板”。在动手改任何东西之前，先复制最近的一份示例，比从零写更安全。

• examples/claude_cli_provider.py 是 31 行的最小 Anthropic provider：展示怎样写一个匹配 Complete 协议的可调用对象，没有 SDK、只有 HTTP。Complete 协议本身定义在 src/veracium/llm/base.py 中 资料来源：examples/claude_cli_provider.py:1-31 资料来源：src/veracium/llm/base.py:1-
• examples/demo.ipynb 是端到端笔记本：默认 sqlite 后端、默认 provider，能跑通 remember → recall → answer 闭环资料来源：examples/demo.ipynb:1-
• examples/langchain_memory.py 演示怎么把 Memory 接到 LangChain 的 memory 抽象上，做替换而非改造
• docs/recipes.md 是面向使用方的“怎么做”入口；docs/api.md 是面向扩展方的“接口长什么样”

社区目前最关心的两份缺口是 examples/openai_provider.py（覆盖 OpenAI / vLLM / Ollama 的 OpenAI 兼容端点）与 MCP 客户端的 .mcp.json 配方（Issue #3、#4），两者都是同一类问题：现成模板缺一段，让第一次接入的人多走一个小时弯路 资料来源：issues/3 资料来源：issues/4

2. 编写自定义 `Complete` provider

Veracium 是 bring-your-own-model：任何满足 Complete 协定的可调用对象都可以注入 Memory(provider=...)。要写一个新的 provider，复制 examples/claude_cli_provider.py 然后只改三处：

1. 导入 SDK：例如 OpenAI、httpx、或裸 urllib；不要 import veracium.llm.* 之外的任何内部模块
2. **实现 __call__(self, prompt: str, *, system: str | None = None) -> str**：单字符串进、单字符串出；不要在内部捕获异常往外冒，让 Memory 自己决定怎么降级
3. 隐藏密钥：从 os.environ 读取而不是参数注入，这样 veracium selfcheck 的 preflight 才能在缺失时给出清晰的安装提示（v0.2.4 新增的行为）资料来源：releases/v0.2.4

常见的失败模式：

• 试图把流式响应（stream=True）直接返回——协议是同步字符串；要流式请在外层聚合
• 解析 JSON 时把整段 extract_json 的输出再 json.loads 一次——extract_json 已经返回 Python 对象了 资料来源：src/veracium/_json.py:1-

3. 自定义 `Store` 后端

Store 接口刻意保持小巧（edge / episode / 失效 / per-user 隔离），src/veracium/store/base.py 是契约，src/veracium/store/sqlite.py 是参考实现 资料来源：src/veracium/store/base.py:1- 资料来源：src/veracium/store/sqlite.py:1-

社区呼声最高的两个新后端都遵循同一份“相同接口、不同落盘”的模式 资料来源：issues/1 资料来源：issues/2：

写新后端时务必保留：每次写都带 user_id 的过滤条件、episode 的不可变追加、edge 的来源（provenance）字段。这些都是 recall 的安全边界，不是实现细节。

4. MCP 客户端配方

veracium[mcp] 暴露一个 MCP server（remember / recall / answer / maintain），文档在 docs/mcp.md，注册表清单 server.json 在仓库根目录（v0.2.3 起符合当前 registry schema）资料来源：docs/mcp.md:1- 资料来源：server.json:1-

接入一段三方客户端只需三步：

1. pip install veracium[mcp]，确保 veracium-mcp 在 PATH（v0.2.2 起 --help / --version 正常工作，缺 key 也会给一行清晰的报错）资料来源：releases/v0.2.2
2. 在客户端配置里指向 veracium-mcp，stdio 传输
3. 配置 ANTHROPIC_API_KEY（或对应 provider 的环境变量），否则 server 在 boot 阶段就会拒绝启动

Claude Code 的最小 .mcp.json、Claude Desktop 的 claude_desktop_config.json 片段、以及一个编辑器无关的例子，是 Issue #4 申请的官方配方补充——目前还不在文档里，需要手动参考 docs/mcp.md 中的工具清单拼装。

5. 什么时候不算“配方”

三个不算扩展点的改动：

• 修改 gate 分区或 wiki 编译——这是核心安全路径，不要在 examples/ 里改
• 越过 Store 接口直接读写 sqlite 文件——绕过 per-user 隔离
• 把 use_only 推断送回 remember()——这条边界在 v0.1.6 已被封堵（wiki 路径上不再接受）资料来源：releases/v0.1.6

相关资料来源汇总

• 协议层：src/veracium/llm/base.py、src/veracium/store/base.py
• 示例：examples/claude_cli_provider.py、examples/demo.ipynb、examples/langchain_memory.py
• 文档：docs/recipes.md、docs/api.md、docs/mcp.md
• 公网追踪：Issue #1（Postgres）、#2（Neo4j）、#3（OpenAI provider）、#4（MCP 配方）
• 兼容性节点：server.json、v0.2.2 / v0.2.3 / v0.2.4 的 release notes

Pitfall Log / 踩坑日志

项目：veracium-ai/Veracium

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/veracium-ai/Veracium | README/documentation is current enough for a first validation pass.

2. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/veracium-ai/Veracium | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/veracium-ai/Veracium | no_demo; severity=medium

4. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/veracium-ai/Veracium | no_demo; severity=medium

5. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/veracium-ai/Veracium | issue_or_pr_quality=unknown

6. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/veracium-ai/Veracium | release_recency=unknown