xyzzylabs/dent8

# dent8 **一个专为编码 agent 设计的记忆防火墙** —— 它能防止低权限或过期的项目事实悄无声息地覆盖受信任的状态，并能精准重放 agent *为什么* 会相信某件事的完整过程。  查看运行效果：**`cargo run -p dent8-cli -- demo`** —— 一个高权限事实被断言，当低权限来源试图覆盖它时会被拒绝，并且完整性回执会通过经过验证的哈希链来解释结果。 其核心原语是 claim event（声明事件），而不是通用的记忆条目：每一次被接受的写入都会保留来源、证据、权限、时效性、矛盾状态、取代血脉以及可重放性。（名称来源：*dentate gyrus*（齿状回），即海马体中与模式分离相关的结构。） ## 状态 这是一个早期的开源项目。**[docs/STATUS.md](docs/STATUS.md) 是关于已构建功能的唯一事实来源。**简而言之： - **当前可运行：** `dent8 demo`（包含防火墙与重放/解释循环，由 registry 驱动）；完整的 **`assert` / `supersede` / `retract` / `contradict` / `explain` / `replay`** 生命周期均通过防火墙，持久化到本地文件支持的日志中，并**能跨独立调用进行组合**；以及 `dent8 schema postgres`。文件日志是一个**开发存储**（单写入器、非事务性）——其*生产级*后端是 Postgres（M2b）。`dent8 mcp serve` 通过 MCP（stdio JSON-RPC）将完整的信念面暴露给 agent，并受同一防火墙保护。 - **已作为经过测试的库实现：** `ClaimEvent` 模型与重放 fold；具有权限加权仲裁 + retract（撤回）、防洗钱挑战者检查以及规范矛盾硬报警的不可绕过写入路径防火墙（`EventStore::append`）；编码 agent 的 predicate registry（谓词注册表）；完整性回执；时效性评估器；带有血缘和已赢得稳固性审计的策略反事实和实体级重放；以及 serde 规范化 + SHA-256 哈希链。 - **通过对抗性语料库验证**（`cargo test -p dent8-evals`）：MINJA 注入、权限洗钱、规范矛盾和 Sybil 串证**在面对防火墙时均失败 (0/4)**，而**在破坏仅重 recente（仅看时效性）的基线时则全部成功 (4/4)** —— 参见 [docs/evals.md](docs/evals.md)。 - **经过 DB 验证 (M2b)：** v0 Postgres adapter（`PostgresEventStore`，在 `--features adapter` 之后）—— 事务性 append（追加），通过共享的 `arbitrate_events` 实现的防火墙，JSONB 事件日志，**外加物化投影 + 边图**（migration 003），在同一事务中进行 fold，并带有 `projection == fold(log)` 检查。基于 `DATABASE_URL` 的集成测试在真实的 `postgres:16` 上通过。 - **可运行 (v0)：** 一个 MCP server（`dent8 mcp serve`），将完整的信念面（`assert`/`supersede`/`retract`/`contradict`/`explain`/`replay`）作为工具暴露出来，外加 `resources/list`/`resources/read` 和 JSON-RPC 批处理，通过 stdio JSON-RPC 传输，经由共享的防火墙路径。 - **仅设计阶段：** 官方 MCP `rmcp` SDK / 更丰富的传输方式（v0 server 已经支持工具、资源和 JSON-RPC 批处理）以及按列划分的 Postgres 事件表 + `uses_as_evidence` 边（上文中提到的投影和关系图已构建完成）。 可运行的表层在任何情况下都会进行持久化：默认是本地文件开发日志，或者 —— 在设置了 `DENT8_DATABASE_URL` 并以 `--features postgres` 编译时 —— 使用**经过 DB 验证的事务性 Postgres 后端**（每个多事件操作作为一个事务提交）。一个可选的**权限上限**（`dent8 authority`）限制了每个来源可以断言的内容，拒绝超出其注册上限的写入。witness（见证者）作为一个*原语*可运行 —— **`dent8 witness`**（`--features witness`）会发出 Ed25519 签名的树头，并检测内部链重新验证无法检测到的历史重写或回滚。要成为一个强化的多用户产品，目前剩余的差距是**加密级别的调用者身份**（签名授权 —— 即*哪个*来源在调用目前仍然是断言出来的）以及一个**运营级的 witness 服务**（从独立的基础设施按频率进行签名）。[路线图](docs/roadmap.md)和 [docs/STATUS.md](docs/STATUS.md) 正是追踪这些内容的。 ## 初始形态 本仓库优先采用 Postgres。Postgres 是只追加 claim 事件、投影、审计查询以及未来多用户用例的生产级事实来源。DuckDB 和 Parquet 仍然是后续用于重放、取证检查、基准分析和调试器工作流的分析通道。 Workspace crates： - `dent8-core`：类型化领域模型、claim-event 状态机、不变量。 - `dent8-store`：由后端共享的存储和重放 trait。 - `dent8-store-postgres`：Postgres schema 和迁移边界。 - `dent8-cli`：面向运维人员和开发者的 CLI 界面。 命令（关于当前可运行的内容，请参见 [docs/STATUS.md](docs/STATUS.md)）： - `dent8 demo`：端到端运行防火墙 + registry + 重放/解释循环（内存中）。 - `dent8 assert `：通过防火墙断言一个事实，持久化到文件支持的日志中（`DENT8_LOG`）。 - `dent8 supersede `：修改受信任的事实 —— 除非修改的权限能超越现任事实，否则将被拒绝。 - `dent8 retract `：移除受信任的事实 —— 同样，除非其权限能超越现任事实，否则将被拒绝。 - `dent8 contradict `：标记冲突（异议）—— 对事实提出异议并保留双方，即使是来自低权限。 - `dent8 explain `：打印受信任的（或终态）事实的回执。 - `dent8 replay `：重放完整的事件历史 —— 即*为什么*事实会是这样。 - `dent8 schema postgres`：打印初始的 Postgres schema。 - `dent8 mcp serve`：通过 MCP（stdio JSON-RPC）将完整的信念面（工具 + 资源 + JSON-RPC 批处理）暴露给 agent。 ## 项目文档 **状态** - [实现状态](docs/STATUS.md) —— 关于已构建功能的唯一事实来源 **设计** - [项目简报](docs/project-brief.md) - [架构](docs/architecture.md) - [领域模型](docs/domain-model.md) - [信念修正](docs/belief-revision.md) —— dent8 的正式身份（主要视角） - [存储与事件日志](docs/storage.md) - [接口](docs/interfaces.md) - [命名](docs/naming.md) **正确性与安全性** - [形式化验证](docs/formal-verification.md) - [评估策略](docs/evals.md) - [威胁模型](docs/threat-model.md) **规划与研究** - [路线图](docs/roadmap.md) - [相关工作](docs/related-work.md) - [研究档案](docs/research/dossier.md) - [开放研究方向](docs/research/novelty.md) - [训练基质](docs/research/training-substrate.md) - [论文大纲](docs/paper/outline.md) · [预印本草案](docs/paper/preprint.md) - [决策记录](docs/decisions) ## 开发 ``` cargo fmt --all --check cargo clippy --workspace --all-targets -- -D warnings cargo test --workspace cargo run -q -p dent8-cli -- demo # Postgres adapter (M2b, DB-verified) 是 feature-gated 的；其集成测试受 # DATABASE_URL 控制（如果没有则跳过）。通过 Docker 使用一次性 DB： docker compose up -d DATABASE_URL=postgres://postgres:dent8@localhost:5432/dent8 \ cargo test -p dent8-store-postgres --features adapter docker compose down ``` CI ([`.github/workflows/ci.yml`](.github/workflows/ci.yml)) 会运行 workspace 的 fmt/clippy/test 门控，并针对 Postgres 服务容器运行 adapter 测试。 ## 状态 dent8 目前处于 **1.0 之前阶段 (v0.x)** 且属于实验性质 —— API、磁盘上的事件编码以及存储 schema 可能会在次要版本之间发生变化。[`docs/STATUS.md`](docs/STATUS.md) 是关于哪些功能是可运行、仅限库使用还是仅限设计的唯一事实来源，而 [`docs/threat-model.md`](docs/threat-model.md) 准确说明了防火墙能防御什么以及不能防御什么。安全报告：请参见 [`SECURITY.md`](SECURITY.md)。 ## 许可证 根据以下任一许可证授权： - Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) 或 ) - MIT license ([LICENSE-MIT](LICENSE-MIT) 或 ) 由您选择。 除非您明确声明，否则根据 Apache-2.0 许可证的规定，您故意提交以包含在本作品中的任何贡献，均应按上述方式进行双重许可，不附加任何额外的条款或条件。

标签：AI编程助手, MCP, Rust, Streamlit, Zenmap, 事件溯源, 可视化界面, 数据完整性, 智能体记忆, 网络流量审计, 访问控制, 请求拦截, 通知系统