veracium

Veracium

Veracium 是面向 Agent 系统的、具备来源追踪能力的记忆插件 — 持久化的用户专属记忆，可抵御困扰简单 Agent 记忆的注入和虚构问题。来源追踪意味着每条事实都会记录是谁说的：Agent 只是读过的邮件中的说法，绝不会变成它宣称的“事实”。它会记住用户说过的话、过去的交互，以及哪些方法奏效 — 并且会记住这些信息各自的来源。

Veracium 是一个由评估驱动的研究项目（agent-memory）提炼出的生产级成果：以下每项设计选择都有实测结果作为依据，研究中的合成语料测试框架也被复用为回归测试套件。

**研究：**支撑这些发现的评估工具 — 一项面向 Agent 记忆的纵向基准 — 详见 Q. Spencer，《“Ground Truth First: A Longitudinal Evaluation Instrument for Agent Memory, and the Tenure Crossover in Memory-Architecture Rankings”》（arXiv:2607.21962，2026 年）。

为何采用这种设计

• **类型化图谱 + 带日期的片段构成权威数据存储。**实体事实以关系边的形式存储（带有不可伪造的来源信息）；交互历史则存储为带日期的片段。精选的“维基”视图由此编译并缓存 — 它绝不是事实来源。（这种分层设计在短期和 9 周的评估中都表现出色；扁平存储方案在其中一种情境下均告失败。）
• **只取代，不抹除。**单值事实（雇主、地点、截止日期）只保留一个当前值，同时将先前值保留为历史记录 — 因此仍可回答“X 过去是什么？”。可以同时持有多个值的事实（偏好、测量值、健康状况）则会累积记录。（这是商业记忆系统处理得最差的类别；Veracium 在此表现最强。）
• **表示方式本身就是安全控制。**第三方说法（收到的邮件、外部文档）会通过结构进行隔离 — 存储为以提出说法者为主体的 third_party_claim 边，绝不会作为用户事实。内容类型隔离会拦截有关义务、债务、续订的说法，无论它们看起来多么可信。（在涵盖冒充联系人的完整可信度阶梯测试中，均能抵御攻击。） 这是什么，以及不是什么：存储负责管理保留、检索、描述和推荐 — 也就是它会说什么，以及如何标注内容。它不会实例化、授权或执行任何操作；这些都属于宿主的测试框架。如果没有专用的测试框架路径来使用这些标签，Veracium 的信任类别就只是建议性标注，而非强制执行。
• **模型由你选择。**Veracium 不会持有你的 API 密钥，也不会替你选择模型；它会调用你提供的 Complete 可调用对象。软件包内附带一个 Anthropic 参考提供程序。
• **默认采用嵌入式部署。**无需外部服务：只需一个 SQLite 文件。之后可通过 Store 接口切换到 Neo4j/Postgres。

安装

pip install "veracium[anthropic]"   # core + the reference LLM provider

Python 和 SQLite 要求。 Veracium 需要 Python 3.14 或更高版本，目前只会在经过验证的 SQLite 构建版本上打开或创建存储：Ubuntu 24.04 打包的 SQLite 3.45.1。链接到该系统 SQLite 的 Python 3.14 可以运行，正如 GitHub 的 setup-python 构建版本一样；uv、python.org 和 Homebrew 的 3.14 构建版本捆绑了更新的 SQLite，即使是全新的存储也会被拒绝。Ubuntu 24.04 自带的系统 Python 是 3.12，低于最低版本要求：在此环境中，pip 会安装仍支持它的最后一个版本 0.26.1。在所有其他 SQLite 构建版本上——包括其他 3.45.1 构建版本，因为检查会精确到构建版本——它都会拒绝创建存储，也会拒绝打开现有存储。因此，切换到 SQLite 版本不同的 Python 后，先前的存储将无法打开，直到支持该构建版本为止。版本检查只能表明你的版本不受支持：如果运行 python -c "import sqlite3; print(sqlite3.sqlite_version)" 输出的不是 3.45.1，就会被拒绝；3.45.1 是必要条件，但并非充分条件。未来计划扩大 SQLite 支持范围。

附加项：[mcp] 会添加 MCP 服务，[dev] 会添加 pytest。核心部分仅依赖 pydantic。如需从源代码开始使用：

git clone https://github.com/veracium-ai/Veracium.git && cd Veracium
pip install -e ".[anthropic,dev]"

链接：文档 · veracium.ai · PyPI

使用（库）

from veracium import Memory, EvidenceAuthor, EvidenceContext
from veracium.llm.anthropic import AnthropicComplete

mem = Memory(llm=AnthropicComplete())   # or pass your own Complete callable

# Remember interactions. `author` says WHO wrote the event; `context` is
# your positive attestation of HOW you captured it. Without a context the
# content class floors to derived(THIRD_PARTY) — never assertable — so a
# host that means "I captured this first-hand" says so:
mem.remember("alice", "USER: I'm vegetarian and have a dog named Ollie.",
             context=EvidenceContext.direct())
mem.remember("alice", "From billing@scam: you owe $900.",
             author=EvidenceAuthor.THIRD_PARTY, event_type="email",
             source_id="billing-mailbox",   # third-party content needs a source id
             context=EvidenceContext.direct())

# Recall grounded, provenance-flagged context for a prompt.
ctx = mem.recall("alice", "suggest a lunch spot")
print(ctx.context)   # states the vegetarian constraint; the $900 "claim" is
                     # rendered under a never-assert flag, not as a fact.

没有 Anthropic API 密钥？AnthropicComplete 只是一个便捷选项——Veracium 可以调用你提供的任意 Complete 可调用对象。若要在无需配置 SDK 或密钥的情况下运行，可以封装已有的客户端；examples/claude_cli_provider.py 将 claude CLI 封装为可直接替换的提供方（from claude_cli_provider import ClaudeCLIComplete），而 examples/openai_provider.py 则通过 OpenAIComplete 封装任意兼容 OpenAI 的聊天补全 API （OpenAI 本身、vLLM、Ollama 的 /v1 端点）。使用 OpenAIComplete(base_url=...) 将其指向本地服务，并通过 models 覆盖模型名称，填入你的服务所提供的模型名称即可。

使用（MCP）

veracium-mcp 向任何兼容 MCP 的 Agent（Claude Desktop/Code 等）提供 remember / recall / answer / maintain 工具，无需在主机端安装 Python。配置 JSON 和工具参考请参阅 docs/mcp.md。

文档

在线文档：veracium-ai.github.io/Veracium

• examples/demo.ipynb — 骗局邮件注入演示，可端到端运行 （在 Colab 中打开）。
• examples/langchain_memory.py — 将 Veracium 用作 LangChain 聊天应用的 长期记忆层（按会话密钥划分的混合方案： LangChain 缓存近期对话轮次，Veracium 保存带有来源信息和隔离机制的持久事实； 你现有的 LangChain 模型为两者提供支持）。
• docs/concepts.md — 心智模型：边、事件片段与编译后的 wiki， 来源信息与作者身份、隔离机制、拒答门控、生命周期。
• docs/recipes.md — 简短的复制粘贴示例，每项能力各一个（隔离、混合来源、 预算受限的召回、可移植性、反馈动词、审计、本地模型）。
• docs/api.md — 公共 API：Memory、MemoryConfig、 EvidenceAuthor，以及如何提供自己的 LLM 可调用对象或存储。
• docs/mcp.md — 运行和注册 MCP 服务。
• docs/design-rationale.md — 为什么没有 update()/delete()、不提供无需 LLM 的提取、不执行 TTL 清理，以及真正列入路线图的内容。
• docs/telemetry.md — 可选择启用的匿名、无内容使用统计信息（默认关闭）。
• docs/diagnostics.md — 可选择启用的错误报告：本地优先的错误日志，经同意后发送已脱敏的数据。
• ROADMAP.md · CHANGELOG.md

状态

经过验证的分层设计已实现并通过测试（44 项离线测试，以及选择性启用的实时层级：验收评估和真实语料鲁棒性测试框架），并达到其自身的研究声明标准（5/5，0 条注入断言）。路线图 v0.1–v0.7 已完成，另有选择性启用的遥测、自检、经用户同意的错误报告和操作审计日志。请参阅 ROADMAP.md。

许可证

MIT