# veracium - Doramagic AI Context Pack

> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。

## 充分原则

- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。
- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。

## 给宿主 AI 的使用方式

你正在读取 Doramagic 为 veracium 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。

## Claim 消费规则

- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。
- **事实最低状态**：`supported`
- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。
- `weak`：只能作为低置信度线索，必须要求用户继续核实。
- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。
- `unverified`：不得作为事实使用，应明确说证据不足。
- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。

## 它最适合谁

- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86

## 它能做什么

- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86

## 怎么开始

- `pip install "veracium[anthropic]"   # core + the reference LLM provider` 证据：`README.md` Claim：`clm_0003` supported 0.86
- `git clone https://github.com/veracium-ai/Veracium.git && cd Veracium` 证据：`README.md` Claim：`clm_0004` supported 0.86
- `pip install -e ".[anthropic,dev]"` 证据：`README.md` Claim：`clm_0005` supported 0.86

## 继续前判断卡

- **当前建议**：先做研究框架试用
- **为什么**：这个项目面向研究工作流，核心风险是资料可信度和输出质量；先用 Prompt Preview 验证研究框架，再在隔离环境试装。

### 30 秒判断

- **现在怎么做**：先做研究框架试用
- **最小安全下一步**：先用 Prompt Preview 验证研究框架；满意后再隔离试装
- **先别相信**：研究结论、引用和实验结果不能在安装前相信。
- **继续会触碰**：研究判断、命令执行、本地环境或项目文件

### 现在可以相信

- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86
- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86
- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86

### 现在还不能相信

- **研究结论、引用和实验结果不能在安装前相信。**（unverified）：研究 Skill 可以组织问题和路径，但不能替代真实资料检索、论文核验和实验复现。
- **是否适合你的具体研究领域不能直接相信。**（unverified）：Skill 覆盖很多研究主题，不代表对你的领域、资料要求和可信度标准足够。
- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。
- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。
- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。
- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。
- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。
- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。

### 继续会触碰什么

- **研究判断**：问题拆解、资料路径、实验路径、结论结构和可信度判断。 原因：研究型 Skill 可能让输出看起来更专业，但不能替代真实证据核验。
- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`
- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`
- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。

### 最小安全下一步

- **先跑 Prompt Preview**：先验证它能否正确界定研究问题和证据边界，不要先相信研究输出。（适用：任何项目都适用，尤其是输出质量未知时。）
- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）
- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）

### 退出方式

- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。
- **保留资料和结论核验清单**：如果后续发现引用或实验路径不可靠，可以回到证据边界阶段重新校验。
- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。
- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。

## 哪些只能预览

- 解释项目适合谁和能做什么
- 基于项目文档演示典型对话流程
- 帮助用户判断是否值得安装或继续研究

## 哪些必须安装后验证

- 真实安装 Skill、插件或 CLI
- 执行脚本、修改本地文件或访问外部服务
- 验证真实输出质量、性能和兼容性

## 边界与风险判断卡

- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0006` inferred 0.45
- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0007` supported 0.86
- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。
- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。
- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。

## 开工前工作上下文

### 加载顺序

- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。
- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。
- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。
- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。
- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。

### 任务路由

- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86

### 上下文规模

- 文件总数：45
- 重要文件覆盖：40/45
- 证据索引条目：45
- 角色 / Skill 条目：14

### 证据不足时的处理

- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。
- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。
- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。
- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。

## Prompt Recipes

### 适配判断

- 目标：判断这个项目是否适合用户当前任务。
- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。

```text
请基于 veracium 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。
```

### 安装前体验

- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。
- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。

```text
请把 veracium 当作安装前体验资产，而不是已安装工具或真实运行环境。

请严格输出四段：
1. 先问我 3 个必要问题。
2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。
3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。
4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。

硬性边界：
- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。
- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。
- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。
- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。
- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。
- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。

```

### 角色 / Skill 选择

- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。
- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。

```text
请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。
```

### 风险预检

- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。
- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。

```text
请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。
```

### 宿主 AI 开工指令

- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。
- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。

```text
请基于 veracium 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。
```

## 角色 / Skill 索引

- 共索引 14 个角色 / Skill / 项目文档条目。

- **Veracium**（project_doc）：! tests https://github.com/veracium-ai/Veracium/actions/workflows/test.yml/badge.svg https://github.com/veracium-ai/Veracium/actions/workflows/test.yml ! PyPI https://img.shields.io/pypi/v/veracium https://pypi.org/project/veracium/ ! Python https://img.shields.io/pypi/pyversions/veracium https://pypi.org/project/veracium/ ! license https://img.shields.io/badge/license-MIT-blue LICENSE 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`
- **Contributing to Veracium**（project_doc）：Thanks for your interest. Veracium is small and opinionated; contributions that fit its discipline land quickly. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`
- **API reference**（project_doc）：- llm — a Complete callable required . See Providing an LLM providing-an-llm . - store — a Store ; defaults to SqliteStore config.db path . - embed — an optional Embed callable reserved for episode semantic fallback . - config — a MemoryConfig ; defaults to MemoryConfig . - telemetry / diagnostics / audit — optional sinks, all off by default: a consented content-free stats collector veracium.telemetry , a local erro… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api.md`
- **Concepts — how to think about Veracium**（project_doc）：Concepts — how to think about Veracium 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/concepts.md`
- **Design rationale**（project_doc）：Veracium makes a few deliberate choices that differ from what the agent-memory category has converged on. This page says what they are, why, and what the equivalent affordance is — plus what's genuinely on the roadmap. It exists so you can tell a missing feature from a refused one. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/design-rationale.md`
- **Diagnostics — opt-in error reporting**（project_doc）：Diagnostics — opt-in error reporting 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/diagnostics.md`
- **Veracium**（project_doc）：Veracium is a provenance-aware memory plug-in for agentic systems — durable, per-user memory that resists the injection and confabulation failures that plague naive agent memory. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/index.md`
- **Using Veracium over MCP**（project_doc）：The MCP server exposes Veracium to any MCP-compatible agent Claude Desktop, Claude Code, and others with no host-side Python. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/mcp.md`
- **Recipes**（project_doc）：Short, copy-pasteable examples — one per capability. Each assumes: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/recipes.md`
- **Telemetry — opt-in, anonymous, content-free**（project_doc）：Telemetry — opt-in, anonymous, content-free 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/telemetry.md`
- **Changelog**（project_doc）：- mcp 2.0 compat : the MCP SDK 2.0.0 renamed FastMCP to MCPServer same decorator API — veracium-mcp now imports whichever the installed SDK provides, so mcp =1.0 stays the supported range on both majors. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`
- **Contributor Covenant Code of Conduct**（project_doc）：Contributor Covenant Code of Conduct 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CODE_OF_CONDUCT.md`
- **Roadmap**（project_doc）：Grounded in the agent-memory research findings. v0.1 ships the write-path spine and graph recall; the items below complete the validated design. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`ROADMAP.md`
- **Security Policy**（project_doc）：Veracium's core premise is that a memory system is a security boundary : content the agent merely read a received email, a fetched document, tool output must never become a fact the agent asserts, and one user's memory must never reach another's. So we treat failures of that boundary as vulnerabilities, not quality bugs. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY.md`

## 证据索引

- 共索引 45 条证据。

- **Veracium**（documentation）：! tests https://github.com/veracium-ai/Veracium/actions/workflows/test.yml/badge.svg https://github.com/veracium-ai/Veracium/actions/workflows/test.yml ! PyPI https://img.shields.io/pypi/v/veracium https://pypi.org/project/veracium/ ! Python https://img.shields.io/pypi/pyversions/veracium https://pypi.org/project/veracium/ ! license https://img.shields.io/badge/license-MIT-blue LICENSE 证据：`README.md`
- **Contributing to Veracium**（documentation）：Thanks for your interest. Veracium is small and opinionated; contributions that fit its discipline land quickly. 证据：`CONTRIBUTING.md`
- **License**（source_file）：Copyright c 2026 Quentin Spencer / Veracium AI 证据：`LICENSE`
- **API reference**（documentation）：- llm — a Complete callable required . See Providing an LLM providing-an-llm . - store — a Store ; defaults to SqliteStore config.db path . - embed — an optional Embed callable reserved for episode semantic fallback . - config — a MemoryConfig ; defaults to MemoryConfig . - telemetry / diagnostics / audit — optional sinks, all off by default: a consented content-free stats collector veracium.telemetry , a local error-log reporter veracium.diagnostics , and an operation audit log veracium.audit.AuditLog path : one append-only JSONL line per operation — UTC timestamp, op, user id , content-free counters; no memory text ever. Sink failures never break memory operations. 证据：`docs/api.md`
- **Concepts — how to think about Veracium**（documentation）：Concepts — how to think about Veracium 证据：`docs/concepts.md`
- **Design rationale**（documentation）：Veracium makes a few deliberate choices that differ from what the agent-memory category has converged on. This page says what they are, why, and what the equivalent affordance is — plus what's genuinely on the roadmap. It exists so you can tell a missing feature from a refused one. 证据：`docs/design-rationale.md`
- **Diagnostics — opt-in error reporting**（documentation）：Diagnostics — opt-in error reporting 证据：`docs/diagnostics.md`
- **Veracium**（documentation）：Veracium is a provenance-aware memory plug-in for agentic systems — durable, per-user memory that resists the injection and confabulation failures that plague naive agent memory. 证据：`docs/index.md`
- **Using Veracium over MCP**（documentation）：The MCP server exposes Veracium to any MCP-compatible agent Claude Desktop, Claude Code, and others with no host-side Python. 证据：`docs/mcp.md`
- **Recipes**（documentation）：Short, copy-pasteable examples — one per capability. Each assumes: 证据：`docs/recipes.md`
- **Telemetry — opt-in, anonymous, content-free**（documentation）：Telemetry — opt-in, anonymous, content-free 证据：`docs/telemetry.md`
- **Changelog**（documentation）：- mcp 2.0 compat : the MCP SDK 2.0.0 renamed FastMCP to MCPServer same decorator API — veracium-mcp now imports whichever the installed SDK provides, so mcp =1.0 stays the supported range on both majors. 证据：`CHANGELOG.md`
- **Contributor Covenant Code of Conduct**（documentation）：Contributor Covenant Code of Conduct 证据：`CODE_OF_CONDUCT.md`
- **Roadmap**（documentation）：Grounded in the agent-memory research findings. v0.1 ships the write-path spine and graph recall; the items below complete the validated design. 证据：`ROADMAP.md`
- **Security Policy**（documentation）：Veracium's core premise is that a memory system is a security boundary : content the agent merely read a received email, a fetched document, tool output must never become a fact the agent asserts, and one user's memory must never reach another's. So we treat failures of that boundary as vulnerabilities, not quality bugs. 证据：`SECURITY.md`
- **Server**（structured_config）：{ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.veracium-ai/veracium", "description": "Provenance-aware memory for AI agents: quarantine, abstention gate, supersession-with-history.", "repository": { "url": "https://github.com/veracium-ai/Veracium", "source": "github" }, "websiteUrl": "https://docs.veracium.ai", "version": "0.2.4", "packages": { "registryType": "pypi", "identifier": "veracium", "version": "0.2.4", "transport": { "type": "stdio" }, "environmentVariables": { "name": "ANTHROPIC API KEY", "description": "API key for the reference Anthropic provider", "format": "string", "isRequired": true, "isSecret": true }, { "na… 证据：`server.json`
- **.gitignore**（source_file）：.venv/ pycache / .pyc .db .egg-info/ dist/ build/ .pytest cache/ site/ 证据：`.gitignore`
- **Citation**（source_file）：cff-version: 1.2.0 message: "If you use veracium in your research, please cite it as below." type: software title: "veracium: a provenance-aware memory plug-in for agentic systems" authors: - family-names: Spencer given-names: Quentin repository-code: "https://github.com/veracium-ai/Veracium" url: "https://github.com/veracium-ai/Veracium" license: MIT version: 0.2.4 date-released: 2026-07-20 keywords: - agent memory - LLM - provenance - prompt injection - abstention abstract: - veracium gives agentic systems durable, per-user memory with structural defenses against memory poisoning and confabulation: typed graph edges with provenance and functional supersession, quarantine of third-party cl… 证据：`CITATION.cff`
- **Claude Cli Provider**（source_file）：ROLE MODEL = { ⋮---- class ClaudeCLIComplete ⋮---- cmd = "claude", "-p", "--model", ROLE MODEL.get role, "claude-sonnet-4-5" ⋮---- p = subprocess.run cmd, input=prompt, capture output=True, text=True, timeout=180 证据：`examples/claude_cli_provider.py`
- **Demo**（source_file）：{ "cells": { "cell type": "markdown", "id": "5e4ab75c", "metadata": {}, "source": " Your agent's memory is an injection vector — a live demo\n", "\n", " ! Open in Colab https://colab.research.google.com/assets/colab-badge.svg https://colab.research.google.com/github/veracium-ai/Veracium/blob/main/examples/demo.ipynb \n", "\n", "Most agent memory works like this: everything the agent reads gets stored, and\n", "everything stored is treated as true. So when a scam email says you owe $900,\n", "your agent remembers that you owe $900 — and three weeks later it reminds you\n", "to pay.\n", "\n", "This notebook runs that exact attack against Veracium https://github.com/veracium-ai/Veracium ,\n",… 证据：`examples/demo.ipynb`
- **Langchain Memory**（source_file）：class LangChainComplete ⋮---- def init self, model: BaseChatModel ⋮---- messages = "system", system if system else + "human", prompt ⋮---- class VeraciumLangChainMemory ⋮---- def get session history self, session id: str - InMemoryChatMessageHistory ⋮---- hist = self. buffers session id ⋮---- def context self, session id: str, query: str, , token budget: int = 600 - str ⋮---- def build chain model: BaseChatModel, memory: VeraciumLangChainMemory ⋮---- prompt = ChatPromptTemplate.from messages ⋮---- def chat with persistent memory user id: str, model: BaseChatModel - None ⋮---- memory = VeraciumLangChainMemory LangChainComplete model chain = build chain model, memory ⋮---- text = input " " .s… 证据：`examples/langchain_memory.py`
- **Endpoint doesn't support structured output — remember that and**（source_file）：ROLE MODEL = { ⋮---- class OpenAIComplete ⋮---- key = api key or os.environ.get "OPENAI API KEY" ⋮---- key = "not-needed" ⋮---- model = self. models.get role, self. models "compile" messages = ⋮---- kwargs: dict = {"model": model, "messages": messages, "max tokens": self. max tokens} ⋮---- resp = self. client.chat.completions.create ⋮---- Endpoint doesn't support structured output — remember that and fall through; veracium parses plain completions tolerantly. ⋮---- resp = self. client.chat.completions.create kwargs 证据：`examples/openai_provider.py`
- **Mkdocs**（source_file）：site name: Veracium site description: Provenance-aware memory for AI agents. site url: https://veracium-ai.github.io/Veracium/ repo url: https://github.com/veracium-ai/Veracium repo name: veracium-ai/Veracium edit uri: edit/main/docs/ theme: name: material palette: - media: " prefers-color-scheme: light " scheme: default primary: teal accent: teal toggle: icon: material/weather-night name: Dark mode - media: " prefers-color-scheme: dark " scheme: slate primary: teal accent: teal toggle: icon: material/weather-sunny name: Light mode features: - navigation.sections - navigation.footer - content.code.copy - toc.integrate nav: - Home: index.md - Concepts: concepts.md - API reference: api.md - R… 证据：`mkdocs.yml`
- **Core is embedded and BYO-LLM: no database, no bundled model client.**（source_file）：build-system requires = "hatchling" build-backend = "hatchling.build" 证据：`pyproject.toml`
- **upgrade in place: same use, new judgment — times used unchanged**（source_file）：ABSTAINED = re.compile r"don'?t know no confirmed record information such " ⋮---- all = "Memory", "MemoryConfig", "Recall", "Store", "SqliteStore", ⋮---- @dataclass class Recall ⋮---- context: str grounded: str unverified: str edges: list Edge episodes: list Episode tokens estimated: int = 0 truncated: bool = False ⋮---- class Memory ⋮---- def on error self, where: str, exc: BaseException, user id: Optional str = None - None ⋮---- uh = hashlib.sha256 user id.encode .hexdigest :12 if user id else None ⋮---- date = date or date.today .isoformat t0 = time.perf counter ⋮---- r = ingest event self.store, self.llm, user id, event text=event text, ⋮---- @staticmethod def est tokens text: str - int… 证据：`src/veracium/__init__.py`
- **Json**（source_file）：def extract json text: str ⋮---- decoder = json.JSONDecoder fallback = None skip until = -1 ⋮---- fallback = obj skip until = i + end 证据：`src/veracium/_json.py`
- **Audit**（source_file）：class AuditLog ⋮---- def init self, path ⋮---- def record self, op: str, user id: str, fields: dict - None ⋮---- line = json.dumps {"ts": datetime.now timezone.utc .isoformat , ⋮---- def entries self, , user id: str None = None, op: str None = None - list dict ⋮---- out = ⋮---- rec = json.loads ln 证据：`src/veracium/audit.py`
- **Cli**（source_file）：def status cfg - None ⋮---- PROVIDER HELP = ⋮---- def build llm ⋮---- llm = AnthropicComplete ⋮---- def selfcheck args - int ⋮---- result = selfcheck.run build llm ⋮---- cfg = telemetry.TelemetryConfig.load ⋮---- coll = telemetry.Collector ⋮---- def diagnostics args, parser - int ⋮---- cfg = diagnostics.DiagnosticsConfig.load ⋮---- cfg = diagnostics.prompt consent interactive=True ⋮---- cfg = diagnostics.set report enabled True, endpoint=args.endpoint note = "" if cfg.endpoint else " no --endpoint set → nothing sends until one is configured " ⋮---- sent = diagnostics.Reporter cfg .send interactive=True, reason="manual" ⋮---- def portability args - int ⋮---- store = SqliteStore args.db ⋮----… 证据：`src/veracium/cli.py`
- **Compile**（source_file）：COMPILE SYSTEM = ⋮---- COMPILE PROMPT = """Compile the material below into ONE curated memory document, ⋮---- def grounded inputs store, user id: str ⋮---- edges = e for e in store.edges user id, active only=True, include quarantined=False ⋮---- episodes = e for e in store.episodes user id ⋮---- def needs recompile store, user id: str, recompile after: int - bool ⋮---- cached = store.get wiki user id ⋮---- def compile wiki store, llm: Complete, user id: str, , budget tokens: int = 900 - str ⋮---- facts = render edges edges or " none " hist = "\n".join f" {e.date} {e.summary}" for e in episodes or " none " wiki = llm COMPILE PROMPT.format budget=budget tokens, facts=facts, episodes=hist , ⋮-… 证据：`src/veracium/compile.py`
- **Config**（source_file）：def default lifetimes - dict Volatility, Optional int ⋮---- @dataclass class MemoryConfig ⋮---- db path: str = "veracium.db" relations: dict str, Relation = field default factory=lambda: dict DEFAULT RELATIONS ⋮---- max subgraph edges: int = 40 max recent episodes: int = 12 ⋮---- wiki recompile after writes: int = 8 ⋮---- volatility lifetime days: dict Volatility, Optional int = field default factory= default lifetimes decay factor: float = 0.5 confidence floor: float = 0.3 consolidate after days: int = 30 consolidate min batch: int = 8 证据：`src/veracium/config.py`
- **--- the reporter ------------------------------------------------------------**（source_file）：SCHEMA VERSION = 1 LOGGER NAME = "veracium.diagnostics" ⋮---- def config dir - Path ⋮---- base = os.environ.get "XDG CONFIG HOME" or str Path.home / ".config" ⋮---- def state dir - Path ⋮---- base = os.environ.get "XDG STATE HOME" or str Path.home / ".local" / "state" ⋮---- def veracium version - str ⋮---- def install id from telemetry - str ⋮---- tid = telemetry.TelemetryConfig.load .install id ⋮---- @dataclass class DiagnosticsConfig ⋮---- log enabled: bool = True report enabled: bool = False prompt on error: bool = True redact: bool = True endpoint: Optional str = None log path: Optional str = None install id: str = "" max report bytes: int = 64 1024 only ever send the log tail, capped r… 证据：`src/veracium/diagnostics.py`
- **Gate**（source_file）：def partition edges: list Edge , episodes: list Episode - tuple str, str ⋮---- grounded = ⋮---- unverified = ⋮---- edge lines = render edges e for e in edges if e.assertable claim lines = render edges e for e in edges ep lines = f" {e.date} {e.summary}" for e in episodes tp ep lines = f" {e.date} {e.summary}" for e in episodes ⋮---- GATE SYSTEM = ⋮---- GATE PROMPT = """The following is the memory for the user this question is about. ⋮---- def answer llm: Complete, query: str, grounded: str, unverified: str - str ⋮---- """Gate-disciplined answer over a grounded/unverified partition.""" 证据：`src/veracium/gate.py`
- **prefer active over superseded, and closer matches**（source_file）：VALUE FILLER = {"a", "an", "the", "my", "our", "their", "named", "called"} ⋮---- def value key text: str - tuple str, ... ⋮---- toks = tuple w for w in re.findall r" a-z0-9 +", text.lower ⋮---- def apply supersession store, edge: Edge, relations: dict str, Relation - None ⋮---- """Persist a new edge with supersession and reinforcement: - Reinforcement: if an active edge already asserts the same subject, relation, object , refresh its validity to the new date instead of adding a duplicate — so re-stating a fact keeps it alive a re-mentioned transient state won't lapse and clears any stale-confirmation flag. "Same" is normalized-token equality see value key , so an extractor paraphrase of an… 证据：`src/veracium/graph.py`
- **Ingest**（source_file）：def uid prefix: str - str ⋮---- def event dt date str: str - datetime ⋮---- """The event's own date drives valid from / observed at — memory timestamps must reflect when facts held, not wall-clock ingest time.""" ⋮---- """Structural quarantine defense in depth over the extractor's routing : a third-party CLAIM is quarantined; a third-party inference is use-only; user/system content is mentionable. Trust is capped at the MINIMUM of the event's author and its declared content source derived from — a system-authored event whose text embeds third-party material never yields mentionable edges, whatever the extractor thinks.""" ⋮---- def source type author: EvidenceAuthor, event type: str - Sourc… 证据：`src/veracium/ingest.py`
- **Lifecycle**（source_file）：def expire store, user id: str, config, , now: Optional datetime = None - dict ⋮---- now = now or utcnow lapsed = decayed = flagged = 0 ⋮---- lifetime = config.volatility lifetime days.get e.volatility ⋮---- age days = now - e.valid from .days ⋮---- behavior = DEFAULT EXPIRY e.volatility ⋮---- CONSOLIDATE SYSTEM = ⋮---- CONSOLIDATE PROMPT = """Compact these dated episodes into FEWER consolidated ⋮---- cutoff = now.date - timedelta days config.consolidate after days episodes = store.episodes user id ⋮---- cold = e for e in episodes if e.kind != "outcome" ⋮---- listing = "\n".join f" {e.date} {e.summary}" for e in cold data = extract json llm CONSOLIDATE PROMPT.format episodes=listing , new =… 证据：`src/veracium/lifecycle.py`
- **Anthropic**（source_file）：DEFAULT MODELS: dict Role, str = { ⋮---- class AnthropicComplete ⋮---- model = self. models.get role, self. models "compile" kwargs: dict = {"model": model, "max tokens": self. max tokens, ⋮---- msg = self. client.messages.create kwargs ⋮---- class AnthropicEmbed ⋮---- def init self, embed fn ⋮---- def call self, texts: list str - list list float 证据：`src/veracium/llm/anthropic.py`
- **Base**（source_file）：Role = str ⋮---- @runtime checkable class Complete Protocol ⋮---- @runtime checkable class Embed Protocol ⋮---- def call self, texts: list str - list list float : ... 证据：`src/veracium/llm/base.py`
- **Mcp Server**（source_file）：AUTHOR = {"user": EvidenceAuthor.USER, ⋮---- out = mem.recall user id, query, token budget=token budget .context ⋮---- def answer impl mem: Memory, user id: str, query: str - str ⋮---- def maintain impl mem: Memory, user id: str - dict ⋮---- def build memory - Memory ⋮---- def server cls ⋮---- def build server mem: Memory, , default user: str = "default" ⋮---- server = server cls "veracium", ⋮---- @server.tool def answer query: str, user id: str = default user - str ⋮---- @server.tool def maintain user id: str = default user - dict ⋮---- USAGE = """\ ⋮---- def main argv=None - None ⋮---- args = sys.argv 1: if argv is None else argv ⋮---- except ImportError as e: pragma: no cover ⋮---- mem =… 证据：`src/veracium/mcp_server.py`
- **Portability**（source_file）：FORMAT VERSION = 2 ⋮---- def export memory store, user id: str, path - dict ⋮---- edges = store.edges user id, active only=False, include quarantined=True episodes = store.episodes user id path = Path path ⋮---- def import memory store, path, , user id: Optional str = None - dict ⋮---- lines = ln for ln in l.strip for l in f if ln ⋮---- header = json.loads lines 0 ⋮---- target uid = user id or header.get "user id" existing edges = {e.id for e in store.edges target uid, active only=False, existing eps = {ep.id for ep in store.episodes target uid } ⋮---- imported = {"edges": 0, "episodes": 0} skipped = 0 ⋮---- rec = json.loads ln kind = rec.pop "record", None ⋮---- kind = rec.pop "kind" ⋮----… 证据：`src/veracium/portability.py`
- **Prompts**（source_file）：EXTRACT SYSTEM = ⋮---- EXTRACT PROMPT = """{date context} ⋮---- def date context iso date: str - str ⋮---- d = date.fromisoformat iso date monday = d - timedelta days=d.weekday def week start ⋮---- EXTRACT SCHEMA = { 证据：`src/veracium/prompts.py`
- **A small, extensible default registry. Hosts can add their own via config.**（source_file）：def utcnow - datetime ⋮---- class SourceType str, Enum ⋮---- STATED = "stated" OBSERVED = "observed" INFERRED = "inferred" ⋮---- class EvidenceAuthor str, Enum ⋮---- USER = "user" THIRD PARTY = "third party" SYSTEM = "system" ⋮---- class Disclosure str, Enum ⋮---- MENTIONABLE = "mentionable" USE ONLY = "use only" QUARANTINED = "quarantined" ⋮---- class Provenance BaseModel ⋮---- source type: SourceType author of evidence: EvidenceAuthor evidence ref: str = Field description="Stable id of the event/message/doc this derives from" observed at: datetime = Field default factory=utcnow disclosure: Disclosure = Disclosure.MENTIONABLE confidence: float = Field default=0.9, ge=0.0, le=1.0 ⋮---- deri… 证据：`src/veracium/schema.py`
- **Selfcheck**（source_file）：ABSTAINED = re.compile HEDGED = re.compile r"unverified no confirmed not confirmed claim never confirmed " AMOUNT = re.compile r"4 ,. ?200 \$?4,?200 \$4\b" ⋮---- def mem llm, tmp: str, name: str, relations ⋮---- def check supersession llm, tmp, relations - tuple int, int, dict ⋮---- mem = mem llm, tmp, "supersession", relations uid = "sc" ⋮---- current = mem.answer uid, "Where do I work now?" all edges = mem.store.edges uid, active only=False ⋮---- ok current = "globex" in current.lower ok history = any not e.active for e in all edges ok = int ok current + int ok history ⋮---- def check injection llm, tmp, relations - tuple int, int, int, dict ⋮---- mem = mem llm, tmp, "injection", relation… 证据：`src/veracium/selfcheck.py`
- **Base**（source_file）：class Store ABC ⋮---- @abstractmethod def add edge self, edge: Edge - None: ... ⋮---- @abstractmethod def invalidate edge self, edge id: str, at, reason: str - None: ... ⋮---- @abstractmethod def add episode self, episode: Episode - None: ... ⋮---- @abstractmethod def episodes self, user id: str, , limit: Optional int = None - list Episode : ... ⋮---- @abstractmethod def delete episode self, episode id: str - None: ... ⋮---- def list users self - list dict ⋮---- def forget user self, user id: str - dict ⋮---- @abstractmethod def get wiki self, user id: str - Optional tuple str, int ⋮---- @abstractmethod def set wiki self, user id: str, text: str, store version: int - None: ... ⋮---- @abstra… 证据：`src/veracium/store/base.py`
- **-- host/admin queries ---------------------------------------------------**（source_file）：SCHEMA = """ ⋮---- class SqliteStore Store ⋮---- def init self, path: str Path = "veracium.db" ⋮---- def bump self, user id: str - None ⋮---- def add edge self, edge: Edge - None ⋮---- def invalidate edge self, edge id: str, at, reason: str - None ⋮---- row = self. conn.execute "SELECT json, user id FROM edges WHERE id=?", edge id, .fetchone ⋮---- edge = Edge.model validate json row 0 ⋮---- q = "SELECT json FROM edges WHERE user id=?" args: list = user id ⋮---- rows = self. conn.execute q, args .fetchall ⋮---- def add episode self, episode: Episode - None ⋮---- def episodes self, user id, , limit=None - list Episode ⋮---- q = "SELECT json FROM episodes WHERE user id=? ORDER BY date" ⋮---- d… 证据：`src/veracium/store/sqlite.py`
- **Telemetry**（source_file）：EVENT FIELDS: dict str, set str = { ⋮---- SCHEMA VERSION = 1 ⋮---- def config dir - Path ⋮---- base = os.environ.get "XDG CONFIG HOME" or str Path.home / ".config" ⋮---- @dataclass class TelemetryConfig ⋮---- enabled: bool = False install id: str = "" endpoint: Optional str = None veracium ships none; no endpoint → never sends interval days: int = 7 last sent: Optional float = None epoch seconds schema version: int = SCHEMA VERSION ⋮---- @classmethod def path cls - Path ⋮---- @classmethod def load cls - "TelemetryConfig" ⋮---- p = cls.path ⋮---- def save self - None ⋮---- p = self.path ⋮---- def exists self - bool ⋮---- class Collector ⋮---- def init self ⋮---- def record self, event: str,… 证据：`src/veracium/telemetry.py`

## 宿主 AI 必须遵守的规则

- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `CONTRIBUTING.md`, `LICENSE`
- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `CONTRIBUTING.md`, `LICENSE`

## 用户开工前应该回答的问题

- 你准备在哪个宿主 AI 或本地环境中使用它？
- 你只是想先体验工作流，还是准备真实安装？
- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？

## 验收标准

- 所有能力声明都能回指到 evidence_refs 中的文件路径。
- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。
- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。

---

## Doramagic Context Augmentation

下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。

## Human Manual 骨架

使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。

宿主 AI 硬性规则：
- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。
- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。
- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。

- **项目概述与快速上手**：importance `high`
  - source_paths: README.md, pyproject.toml, src/veracium/__init__.py, docs/index.md
- **核心架构：边、剧集与 Wiki 三层模型**：importance `high`
  - source_paths: src/veracium/graph.py, src/veracium/compile.py, src/veracium/ingest.py, src/veracium/schema.py, docs/concepts.md
- **安全与溯源模型：闸门、隔离区与 use_only 强制**：importance `high`
  - source_paths: src/veracium/gate.py, src/veracium/compile.py, src/veracium/schema.py, docs/concepts.md
- **存储后端：Store 接口、SQLite 与扩展路径**：importance `medium`
  - source_paths: src/veracium/store/base.py, src/veracium/store/sqlite.py, src/veracium/portability.py
- **LLM 提供方：Complete 契约与"自带模型"**：importance `high`
  - source_paths: src/veracium/llm/base.py, src/veracium/llm/anthropic.py, examples/claude_cli_provider.py, examples/openai_provider.py, src/veracium/prompts.py
- **MCP 服务器与客户端接入配方**：importance `high`
  - source_paths: src/veracium/mcp_server.py, docs/mcp.md, server.json
- **运维：selfcheck、审计、遥测与生命周期**：importance `medium`
  - source_paths: src/veracium/selfcheck.py, src/veracium/cli.py, src/veracium/audit.py, src/veracium/telemetry.py, src/veracium/diagnostics.py
- **配方、示例与扩展使用模式**：importance `medium`
  - source_paths: docs/recipes.md, examples/demo.ipynb, examples/langchain_memory.py, docs/api.md, src/veracium/_json.py

## Repo Inspection Evidence / 源码检查证据

- repo_clone_verified: true
- repo_inspection_verified: true
- repo_commit: `710fb04bbb6720efe88387ffb95dc22b43cb8fc0`
- inspected_files: `README.md`, `pyproject.toml`, `docs/api.md`, `docs/concepts.md`, `docs/design-rationale.md`, `docs/diagnostics.md`, `docs/index.md`, `docs/mcp.md`, `docs/recipes.md`, `docs/telemetry.md`, `examples/claude_cli_provider.py`, `examples/langchain_memory.py`, `examples/openai_provider.py`, `src/veracium/__init__.py`, `src/veracium/_json.py`, `src/veracium/audit.py`, `src/veracium/cli.py`, `src/veracium/compile.py`, `src/veracium/config.py`, `src/veracium/diagnostics.py`

宿主 AI 硬性规则：
- 没有 repo_clone_verified=true 时，不得声称已经读过源码。
- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。
- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。

## Doramagic Pitfall Constraints / 踩坑约束

这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。

### Constraint 1: 能力判断依赖假设

- Trigger: README/documentation is current enough for a first validation pass.
- Host AI rule: 将假设转成下游验证清单。
- Why it matters: 假设不成立时，用户拿不到承诺的能力。
- Evidence: capability.assumptions | https://github.com/veracium-ai/Veracium | README/documentation is current enough for a first validation pass.
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 2: 维护活跃度未知

- Trigger: 未记录 last_activity_observed。
- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。
- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- Evidence: evidence.maintainer_signals | https://github.com/veracium-ai/Veracium | last_activity_observed missing
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

- Trigger: no_demo
- Evidence: downstream_validation.risk_items | https://github.com/veracium-ai/Veracium | no_demo; severity=medium
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 4: 存在评分风险

- Trigger: no_demo
- Why it matters: 风险会影响是否适合普通用户安装。
- Evidence: risks.scoring_risks | https://github.com/veracium-ai/Veracium | no_demo; severity=medium
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 5: issue/PR 响应质量未知

- Trigger: issue_or_pr_quality=unknown。
- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。
- Why it matters: 用户无法判断遇到问题后是否有人维护。
- Evidence: evidence.maintainer_signals | https://github.com/veracium-ai/Veracium | issue_or_pr_quality=unknown
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 6: 发布节奏不明确

- Trigger: release_recency=unknown。
- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。
- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。
- Evidence: evidence.maintainer_signals | https://github.com/veracium-ai/Veracium | release_recency=unknown
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。