CORTEX Persist

Cryptographically trace what your AI agent knew.

Tamper-evident memory and decision lineage for AI agents. 
Local-first. SHA-256 hash-chained. Merkle-sealed. Audit-ready.

          

快速入门 · API · 安全模型 · 路线图 · 贡献指南

CORTEX 是 AI 代理的可信基础设施。它位于运行时与内存层之间，使事实、决策和衍生状态具备抗篡改性。如果存储的内容之后发生变化，验证将失败。如果需要解释代理在何时知道什么以及接下来做了什么，CORTEX 提供加密追踪而非轶事。 ## 为何不只用日志 / 可观测性？ | 特性 | 日志与可观测性 | CORTEX Persist（信任层） | | :--- | :--- | :--- | | **信任模型** | “信任流程” | **“验证证据”** | | **篡改检测** | 较弱（数据库变更静默） | **加密（SHA-256 + Merkle）** | | **合规证明** | 需手动重建 | **O(1) 可移植 JSON 审计包** | | **代理责任** | 上下文重建模糊 | **数学可辩护的谱系** | ## 使用场景 1. **自主代理：** 证明代理在做出关键、不可逆决策（例如执行交易、发送法律邮件）时拥有的确切上下文。 2. **多代理系统：** 追踪状态在代理和工作流之间的传播。 3. **高合规环境：** 为金融、安全和受监管操作生成审计追踪。 4. **事后取证：** 检测静默变更、篡改或重放的状态。 5. **信任敏感型 AI 产品：** 发货时附带证据而非“感觉”的内存。 ## 为何选择 CORTEX？（不只是一个向量数据库或日志器） 传统日志和标准向量存储无法通过认识论 containment 测试。如果代理产生幻觉，或数据库被动变更，你将失去结构性信任。CORTEX 使变更在数学上可辩护。 | 特性 | 标准日志（Datadog/ELK） | 标准向量数据库（Pinecone/Qdrant） | **CORTEX Persist** | |:---------------------------|:----------------------------|:-------------------------------------|:------------------------------------------| | **主要目标** | 可观察性与调试 | 语义搜索与 RAG | **抗篡改认知谱系** | | **写入完整性** | 可覆盖 / 可编辑 | 静默 CRUD 操作 | **仅追加 + 加密哈希** | | **事实可变性** | 简单（API/管理员访问） | 简单（API/管理员访问） | **抗篡改**（验证揭示变更） | | **证据导出** | 文本转储 | JSON 提取 | **零信任密封审计包** | ### CORTEX 不替换什么（非目标） - **CORTEX 不是语义搜索主数据库：** 继续使用 Qdrant、Pinecone 或 Milvus 处理临时 RAG 块。CORTEX 存储 *决策* 和核心 *事实*。 - **CORTEX 不是可观测性平台：** 继续使用 Datadog 或 ELK 处理服务器指标、APM 和基础字符串日志。 - **CORTEX 不能阻止幻觉：** 来自 LLM 的加密记录谎言仍然是谎言。它只是成为一个 *可审计* 的谎言，如果与之前密封的事实矛盾则会被标记。 ## 部署矩阵 - **抗篡改内存：** 仅追加的账本，用于事实、决策和状态转换。 - **哈希链接记录：** 存储条目间的 SHA-256 链。 - **批量完整性证明：** 用于大规模验证的 Merkle 检查点。 - **确定性审计导出：** 用于内部审查和合规流程的可重现证据。 - **即插即用定位：** 在现有内存存储之上工作，而非替换你的技术栈。 | 环境 | 状态 | 存储 / 扩展 | | :--- | :--- | :--- | | **仅本地** | ✅ **稳定的本地优先核心** | SQLite + WAL + 内置向量搜索。当前最佳支持路径。 | | **自托管** | 🟡 **测试版** | 多租户。API 驱动。Redis 缓存。可插入你的基础设施。 | | **云就绪** | ⏳ **部分 / 路线图** | Postgres/Qdrant/Turso 代码存在于树中；托管云姿态尚未完整。 | ## 产品核心 支持的核心模块包括：**engine**、**ledger**、**crypto**、**memory**、**facts**、**search**、**verification**、**audit**、**CLI**、**database**、**embeddings**、**guards**、**auth**、**core**、**types**。 请参阅 [docs/PRODUCT-CORE.md](docs/PRODUCT-CORE.md) 了解完整稳定层级划分（稳定 / 测试版 / 实验性）。 ## 90 秒演示 ``` # 启动账本 $ cortex init # 存储记忆 $ cortex memory store risk-bot "Transaction flagged: IP mismatch" [+] Fact stored. Ledger hash: 8f4a2b9e... # 验证存储的事实 $ cortex verify 1 [✔] VERIFIED: Fact chain intact. # 篡改尝试（直接数据库变更） $ sqlite3 cortex.db "UPDATE facts SET content='Transaction approved' WHERE id='8f4a2b9e'" # 账本验证 $ cortex trust-ledger verify [✘] TAMPER DETECTED: Hash mismatch at block 8f4a2b9e # 生成合规快照 $ cortex compliance-report ``` ## 快速入门 从最小支持流程开始，快速获得审计证据。 支持的 PyPI 基础流程为 `install -> init -> store -> verify`。 语义搜索、MCP/服务器流程及其他扩展表面可能需要可选额外组件或更完整的本地运行时。 ### 路径 A：从 PyPI 安装（推荐） ``` pip install cortex-persist cortex init cortex memory store risk-bot "Transaction flagged: IP mismatch" cortex trust-ledger verify ``` 对于本地语义嵌入、Chroma 支持的知识同步或即时加速，添加你实际需要的可选额外组件： ``` pip install "cortex-persist[embeddings]" pip install "cortex-persist[knowledge]" pip install "cortex-persist[acceleration]" pip install "cortex-persist[platform]" # macOS keychain support pip install "cortex-persist[api,mcp,daemon,authoring]" # optional server surfaces ``` ### 路径 B：从源码安装（开发） ``` git clone https://github.com/borjamoskv/Cortex-Persist.git cd Cortex-Persist python3 -m venv .venv && source .venv/bin/activate pip install -e . cortex init cortex memory store risk-bot "Transaction flagged: IP mismatch" cortex trust-ledger verify ``` 请参阅 [docs/installation.md](docs/installation.md) 获取完整安装选项和平台特定说明。 ## 集成 CORTEX 封装你现有的状态管理。它不会替换你的嵌入或向量搜索。 ``` import asyncio from cortex import CortexEngine async def main() -> None: engine = CortexEngine() fact_id = await engine.store( project="fin-fraud-bot", content="User approved transaction $5,000", fact_type="decision", tenant_id="customer-123", ) result = await engine.verify_ledger() assert result.get("valid") is True asyncio.run(main()) ``` ## 性能 *典型执行在标准云实例（4 vCPU，16 GB RAM）上。* | 操作 | 中位数 | P95 | 说明 | | :--- | :--- | :--- | :--- | | **内存写入** | ~18 ms | ~35 ms | 本地 SQLite + SHA-256 | | **验证记录** | ~5 ms | ~12 ms | 单块验证 | | **Merkle 检查点** | ~85 ms | ~140 ms | 聚合 10k 条记录 | | **报告导出** | ~400 ms | ~800 ms | 谱系遍历 | ## 威胁模型摘要（信任边界） CORTEX 遵循严格的零信任哲学对待生成式 AI 输出。 - **生成输出是猜想：** 我们将所有 LLM 输出视为热力学不稳定的（`Void-State`）。只有在通过确定性验证膜后，它才成为持久内存。 - **SQL 沙箱：** 代理无法运行任意查询；变更必须通过严格的模式验证和形式 AST 检查点。 - **篡改证据优于访问控制：** 不是寄希望于管理员不编辑行，而是我们对账本进行哈希链式处理，因此任何手动修改都会使内存线程的数学证明失效。 ## 文档 - [**安全与信任模型**](docs/SECURITY_TRUST_MODEL.md) — 加密不变式与保证。 - [**路线图**](ROADMAP.md) — 部署阶段与扩展逻辑。 - [**API 参考**](docs/api.md) — SDK 原语与 REST 端点。 ## 许可证 Apache License 2.0。参见 [LICENSE](LICENSE)。 *由 [borjamoskv.com](https://borjamoskv.com) 构建 · [cortexpersist.com](https://cortexpersist.com)*

标签：AI代理, Merkle树, Python, SHA256, Zenmap, 不可篡改, 人工智能代理, 内存持久化, 决策溯源, 加密证明, 区块链式验证, 可信AI, 可验证AI, 哈希链, 安全存证, 审计追踪, 开源, 搜索引擎查询, 数据完整性, 无后门, 本地优先, 证据保全, 逆向工具, 防篡改