# https://github.com/veracium-ai/Veracium 项目说明书
生成时间：2026-07-29 01:00:01 UTC
## 目录
- [项目概述与快速上手](#page-overview)
- [核心架构：边、剧集与 Wiki 三层模型](#page-architecture)
- [安全与溯源模型：闸门、隔离区与 use_only 强制](#page-security)
- [存储后端：Store 接口、SQLite 与扩展路径](#page-storage)
- [LLM 提供方：Complete 契约与"自带模型"](#page-llm-providers)
- [MCP 服务器与客户端接入配方](#page-mcp)
- [运维：selfcheck、审计、遥测与生命周期](#page-operations)
- [配方、示例与扩展使用模式](#page-recipes)
## 项目概述与快速上手
### 相关页面
相关主题：[核心架构：边、剧集与 Wiki 三层模型](#page-architecture), [LLM 提供方：Complete 契约与"自带模型"](#page-llm-providers)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/veracium-ai/Veracium/blob/main/README.md)
- [pyproject.toml](https://github.com/veracium-ai/Veracium/blob/main/pyproject.toml)
- [src/veracium/__init__.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/__init__.py)
- [docs/index.md](https://github.com/veracium-ai/Veracium/blob/main/docs/index.md)
- [src/veracium/store/base.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/store/base.py)
- [src/veracium/store/sqlite.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/store/sqlite.py)
- [src/veracium/llm/](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/llm/)
- [examples/claude_cli_provider.py](https://github.com/veracium-ai/Veracium/blob/main/examples/claude_cli_provider.py)
- [docs/mcp.md](https://github.com/veracium-ai/Veracium/blob/main/docs/mcp.md)
- [src/veracium/memory.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/memory.py)
# 项目概述与快速上手
## 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 的运行时由三层构成：模型层、记忆层、协议层。下表汇总各层的关键模块与职责：
| 层 | 关键模块 | 职责 |
| --- | --- | --- |
| 模型层 | `src/veracium/llm/` | 定义 `Complete` 协议；提供 Anthropic 参考实现与可注入的自定义 provider |
| 记忆层 | `src/veracium/memory.py`、`src/veracium/store/` | 提炼 episode、维护 typed edges、执行 gate 划分、产出 recall 上下文 |
| 协议层 | `veracium-mcp` CLI、`docs/mcp.md` | 通过 MCP 协议将 `Memory` 暴露给外部 LLM 客户端 |
`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 后端：
```bash
pip install veracium
```
若需要通过 MCP 协议将 Veracium 作为服务端暴露给外部 LLM 客户端，使用可选依赖：
```bash
pip install "veracium[mcp]"
```
可选 extras 对应 README 中说明的扩展场景，可与基础包叠加安装。
资料来源：[pyproject.toml:1-60]()、[README.md:30-90]()
### 3.2 最小示例
完成安装后，可在任意 Python 入口处实例化 `Memory` 并使用其四个核心动词：
```python
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`，无需修改源码：
```python
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]()
---
## 核心架构：边、剧集与 Wiki 三层模型
### 相关页面
相关主题：[安全与溯源模型：闸门、隔离区与 use_only 强制](#page-security), [存储后端：Store 接口、SQLite 与扩展路径](#page-storage)
相关源码文件
以下源码文件用于生成本页说明：
- [src/veracium/graph.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/graph.py)
- [src/veracium/ingest.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/ingest.py)
- [src/veracium/compile.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/compile.py)
- [src/veracium/schema.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/schema.py)
- [src/veracium/store/base.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/store/base.py)
- [src/veracium/store/sqlite.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/store/sqlite.py)
- [src/veracium/gate.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/gate.py)
- [docs/concepts.md](https://github.com/veracium-ai/Veracium/blob/main/docs/concepts.md)
- [docs/design-rationale.md](https://github.com/veracium-ai/Veracium/blob/main/docs/design-rationale.md)
# 核心架构：边、剧集与 Wiki 三层模型
Veracium 的记忆系统由三层结构组成：**剧集（Episodes）→ 边（Edges）→ Wiki**。这一三层模型将"原始输入"、"结构化事实"与"可读摘要"解耦，使记忆既可机读、又能安全检索。下面按数据流向逐层展开。
## 一、剧集层：原始事件的不可变记录
剧集是写入管道的最底层，表示一次未经处理的"对话/事件"。每一个剧集携带：
- 作者角色（如 `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 引用"等价于"可被断言"，避免可信路径上的安全穿越。
```mermaid
flowchart LR
A[Episodes
原始事件] -->|distill / extract_json| B[Edges
带溯源图边]
B -->|gate.partition| C{GROUNDED?}
C -->|是| D[Wiki
编译视图]
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
---
## 安全与溯源模型：闸门、隔离区与 use_only 强制
### 相关页面
相关主题：[核心架构：边、剧集与 Wiki 三层模型](#page-architecture), [运维：selfcheck、审计、遥测与生命周期](#page-operations)
相关源码文件
以下源码文件用于生成本页说明：
- [src/veracium/gate.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/gate.py)
- [src/veracium/compile.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/compile.py)
- [src/veracium/ingest.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/ingest.py)
- [src/veracium/schema.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/schema.py)
- [src/veracium/recall.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/recall.py)
- [docs/concepts.md](https://github.com/veracium-ai/Veracium/blob/main/docs/concepts.md)
# 安全与溯源模型：闸门、隔离区与 use_only 强制
## 模型目的与范围
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]()
## 端到端调用链
```mermaid
flowchart LR
A[remember event] --> B[ingest
作者校验与降级]
B --> C[(Store
edges + episodes)]
C --> D[recall 拉取]
C --> J[compile → wiki]
J --> D
D --> E[gate.partition]
E -->|GROUNDED| F[assertable context]
E -->|USE_ONLY| G[参考上下文
不可断言]
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]()
---
## 存储后端：Store 接口、SQLite 与扩展路径
### 相关页面
相关主题：[核心架构：边、剧集与 Wiki 三层模型](#page-architecture), [运维：selfcheck、审计、遥测与生命周期](#page-operations)
相关源码文件
以下源码文件用于生成本页说明：
- [src/veracium/store/base.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/store/base.py)
- [src/veracium/store/sqlite.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/store/sqlite.py)
- [src/veracium/portability.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/portability.py)
- [src/veracium/store/__init__.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/store/__init__.py)
- [src/veracium/memory.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/memory.py)
# 存储后端：Store 接口、SQLite 与扩展路径
`Store` 是 Veracium 唯一的持久化接口：所有记忆——`Edge`、剧集（episode）、失效标记——都通过该抽象进出底层数据库。`SqliteStore` 是参考实现，社区正在推动的两个生产级扩展是 Postgres 后端（issue #1）与 Neo4j 图数据库后端（issue #2）。三者共享同一份契约，因此可以互换而不影响上层 `Memory` 逻辑。
## 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` 与本地开发默认使用的后端。其设计要点：
| 维度 | 行为 |
| --- | --- |
| 文件形态 | 单文件数据库（默认 `~/.veracium/store.db`），便于开发与备份 |
| 边的物理表示 | 行级记录，类型化 `edge_type` 与 `provenance` JSON 块共位列存 |
| 剧集存放 | 单独表，按 `episode_id` 与 `user_id` 复合索引 |
| 失效机制 | 软删除（`invalidated_at` 时间戳），而非物理 `DELETE`，保留审计链 |
| 用户隔离 | 强制 `WHERE user_id = ?` 谓词贯穿所有读路径 |
资料来源：[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]()
```mermaid
flowchart LR
Memory[Memory 上层 API] --> Store["Store 接口
(base.py)"]
Store --> SQLite["SqliteStore
参考实现"]
Store --> PG["PostgresStore
(issue #1)"]
Store --> Neo["Neo4jStore
(issue #2)"]
SQLite --- Port["portability.py
导出/导入"]
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]()
---
## LLM 提供方：Complete 契约与"自带模型"
### 相关页面
相关主题：[项目概述与快速上手](#page-overview), [配方、示例与扩展使用模式](#page-recipes)
相关源码文件
以下源码文件用于生成本页说明：
- [src/veracium/llm/base.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/llm/base.py)
- [src/veracium/llm/anthropic.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/llm/anthropic.py)
- [examples/claude_cli_provider.py](https://github.com/veracium-ai/Veracium/blob/main/examples/claude_cli_provider.py)
- [examples/openai_provider.py](https://github.com/veracium-ai/Veracium/blob/main/examples/openai_provider.py)
- [src/veracium/prompts.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/prompts.py)
- [src/veracium/cli.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/cli.py)
- [src/veracium/mcp/server.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/mcp/server.py)
# LLM 提供方：Complete 契约与"自带模型"
## 概述与设计动机
Veracium 的 LLM 层采用"自带模型"（bring-your-own-model）架构。任何满足 `Complete` 契约的可调用对象都可以作为 LLM 提供方接入，无需修改核心管线。这一设计将模型推理与记忆机制解耦：Veracium 负责处理摄取、门控、蒸馏与回忆的安全逻辑，而模型仅需提供一致的文本补全接口。`Complete` 契约在 [`src/veracium/llm/base.py`](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/llm/base.py) 中定义，是整个记忆系统的语言模型入口。资料来源：[src/veracium/llm/base.py:1-30]()
社区反馈显示，OpenAI 兼容 API（OpenAI、vLLM、Ollama 的 OpenAI 端点）的接入需求最为迫切，因此官方提供 [`examples/openai_provider.py`](https://github.com/veracium-ai/Veracium/blob/main/examples/openai_provider.py) 作为参考实现。资料来源：[examples/openai_provider.py:1-31]()
## Complete 契约的形态
`Complete` 契约本质上是一个接受提示字符串并返回模型输出字符串的可调用对象。具体形态取决于实现，但其语义约束在所有提供方之间保持一致：
- **输入**：纯文本或经过模板渲染的提示，由 [`src/veracium/prompts.py`](https://github.com/veracium-ai/Veracium/blob/main/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`](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/llm/anthropic.py)，是 Veracium 官方支持的完整 SDK 接入路径。它调用 Anthropic Python SDK 发送消息，并将响应文本提取为字符串。资料来源：[src/veracium/llm/anthropic.py:1-60]()
[`examples/claude_cli_provider.py`](https://github.com/veracium-ai/Veracium/blob/main/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 提供方是否可用：
```mermaid
flowchart LR
A[veracium selfcheck] --> B{Provider 可用?}
B -- 否 --> C[输出安装提示
并退出]
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` 号议题](https://github.com/veracium-ai/Veracium/issues/3) 提议增加 `openai_provider.py` 正式示例，以覆盖 OpenAI、vLLM、Ollama 的 OpenAI 兼容端点。用户实现自定义提供方时，建议遵循以下模式：
1. **签名一致性**：函数签名严格匹配 `Complete` 契约，便于 `Memory` 类直接注入。
2. **早失败**：在导入阶段或首次调用前检查依赖与凭证，避免在 `remember()` 或 `recall()` 流程中段报错。
3. **输出清洗**：确保返回的是纯文本字符串，去除多余的系统消息或工具调用残留。
通过这套契约，Veracium 把模型选择权完全交还给部署者，同时保留了统一的记忆安全语义。
---
## MCP 服务器与客户端接入配方
### 相关页面
相关主题：[项目概述与快速上手](#page-overview), [配方、示例与扩展使用模式](#page-recipes)
相关源码文件
以下源码文件用于生成本页说明：
- [src/veracium/mcp_server.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/mcp_server.py)
- [src/veracium/mcp.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/mcp.py)
- [docs/mcp.md](https://github.com/veracium-ai/Veracium/blob/main/docs/mcp.md)
- [server.json](https://github.com/veracium-ai/Veracium/blob/main/server.json)
- [pyproject.toml](https://github.com/veracium-ai/Veracium/blob/main/pyproject.toml)
- [README.md](https://github.com/veracium-ai/Veracium/blob/main/README.md)
# MCP 服务器与客户端接入配方
## 概述与设计意图
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` 为例：
| MCP 工具 | 作用 | 关键入参 |
| --- | --- | --- |
| `remember` | 蒸馏并持久化一段情景 | `user_id`、`text`（USER/SYSTEM/ASSISTANT 三态之一） |
| `recall` | 按预算检索相关边与情景 | `user_id`、`query`、`budget` |
| `answer` | 在 gate/compile 保护下作答 | `user_id`、`question` |
| `maintain` | 触发 forget/feedback/审计维护 | `user_id`、`verb`、`payload` |
工具实现集中在 `src/veracium/mcp_server.py` 与 `src/veracium/mcp.py` 中，前者负责协议层编解码，后者负责参数到 `Memory` 方法的转译。资料来源：[src/veracium/mcp_server.py:1-80]()
## 客户端接入配方
### Claude Code（`.mcp.json`）
在仓库根目录或用户级 `~/.claude/mcp.json` 中加入：
```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]()
```mermaid
flowchart LR
A[MCP Client
Claude Code / Desktop / 其他] -->|stdio JSON-RPC| B[veracium-mcp]
B --> C[Memory 对象
remember / recall / answer / maintain]
C --> D[(SqliteStore
或自定义 Store)]
C --> E[Complete 提供方
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](https://github.com/veracium-ai/Veracium/issues/4) — 直接推动了本页"客户端接入配方"章节。
- [v0.2.3 — MCP Registry readiness](https://github.com/veracium-ai/Veracium/releases/tag/v0.2.3) — 引入 `server.json` 与 README 的 `mcp-name`。
- [v0.2.2 — veracium-mcp --help/--version](https://github.com/veracium-ai/Veracium/releases/tag/v0.2.2) — 改进了首次安装时的可观测性。
---
## 运维：selfcheck、审计、遥测与生命周期
### 相关页面
相关主题：[项目概述与快速上手](#page-overview), [安全与溯源模型：闸门、隔离区与 use_only 强制](#page-security)
相关源码文件
以下源码文件用于生成本页说明：
- [src/veracium/selfcheck.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/selfcheck.py)
- [src/veracium/cli.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/cli.py)
- [src/veracium/audit.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/audit.py)
- [src/veracium/telemetry.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/telemetry.py)
- [src/veracium/diagnostics.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/diagnostics.py)
- [src/veracium/lifecycle.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/lifecycle.py)
# 运维：selfcheck、审计、遥测与生命周期
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]()
| 检查阶段 | 失败行为（v0.2.4+） | 失败行为（v0.2.4 之前） |
| --- | --- | --- |
| Provider SDK 缺失 | 单行 `pip install ...` 提示并退出 | traceback |
| 缺少 API Key | 单行 "set ANTHROPIC_API_KEY=..." 提示并退出 | traceback |
| 错误本身被计分 | 不计入 assert，单独标记为 ERROR | 被记为 assert，假阳性注入失败 |
## 审计日志（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]()
```mermaid
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]()
---
## 配方、示例与扩展使用模式
### 相关页面
相关主题：[LLM 提供方：Complete 契约与"自带模型"](#page-llm-providers), [MCP 服务器与客户端接入配方](#page-mcp)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/recipes.md](https://github.com/veracium-ai/Veracium/blob/main/docs/recipes.md)
- [docs/api.md](https://github.com/veracium-ai/Veracium/blob/main/docs/api.md)
- [docs/mcp.md](https://github.com/veracium-ai/Veracium/blob/main/docs/mcp.md)
- [examples/demo.ipynb](https://github.com/veracium-ai/Veracium/blob/main/examples/demo.ipynb)
- [examples/claude_cli_provider.py](https://github.com/veracium-ai/Veracium/blob/main/examples/claude_cli_provider.py)
- [examples/langchain_memory.py](https://github.com/veracium-ai/Veracium/blob/main/examples/langchain_memory.py)
- [src/veracium/_json.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/_json.py)
- [src/veracium/llm/base.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/llm/base.py)
- [src/veracium/store/base.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/store/base.py)
- [src/veracium/store/sqlite.py](https://github.com/veracium-ai/Veracium/blob/main/src/veracium/store/sqlite.py)
- [server.json](https://github.com/veracium-ai/Veracium/blob/main/server.json)
# 配方、示例与扩展使用模式
本页汇总 Veracium 的官方示例（`examples/`）、文档配方（`docs/recipes.md`、`docs/mcp.md`），以及围绕自定义 LLM provider 与 store 后端的两条扩展路径。读者应已熟悉 `Memory` 的四个动词（`remember` / `recall` / `answer` / `maintain`）以及 `Complete` 与 `Store` 两个接口。
## 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](https://github.com/veracium-ai/Veracium/issues/3) 资料来源：[issues/4](https://github.com/veracium-ai/Veracium/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](https://github.com/veracium-ai/Veracium/issues/1) 资料来源：[issues/2](https://github.com/veracium-ai/Veracium/issues/2)：
| 后端 | 存储形态 | 适合场景 | 实现要点 |
| --- | --- | --- | --- |
| `SqliteStore`（参考） | 单文件 + JSON 列 | 本地、单用户、评测 | 直接跟 schema 文件读 |
| `PostgresStore` | JSONB 行 | 多实例、生产部署 | mirror sqlite 的列结构，保持 `user_id` 在最左索引 |
| `Neo4jStore`（提议中） | 节点 + 类型化边 | 图查询、邻域、路径 | 原生支持图的递归 |
写新后端时务必保留：每次写都带 `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
---
---
## Doramagic 踩坑日志
项目：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