ContextDB Memory

---

Codex 可以出色地理解代码库，但在下一项任务开始时，仍可能像金鱼一样失去上下文的延续性。ContextDB Memory 为它提供持久的本地项目历史：已经做出的决策、仍然重要的约束、正在推进的目标、已验证的里程碑，以及那些等待有人不再假装它们不存在的未完成事项。

插件会在实质性工作开始时回忆相关上下文，并随着任务进展记录重要状态。它通过捆绑的、无监听器的 MCP 适配器实现此功能；数据库、运行时、密钥和可变记忆都保留在你自己的 Windows 或 Linux 计算机上。

发布状态： 面向 Windows x86-64 和 Linux x86-64 的 0.6.0-alpha.3 开发者预览版。 两种本地配置文件都包含自动钩子、类型化候选图谱、平台专属保管机制、 恢复和卸载控件，以及可独立验证的发布包。可执行文件未经签名，不支持 macOS 和 ARM64， 这也不是托管的 ContextDB 服务。Linux ELF 以 Ubuntu 22.04 / glibc 2.35 为基准； 其他基于 glibc 的 x86-64 发行版需要 glibc 2.35 或更高版本，且未逐一认证。

它会记住什么

记忆类型	示例	为什么会保留
决策	“本地版本仅使用 stdio。”	避免后续任务在没有证据的情况下重新讨论已经确定的架构选择
约束	“此阶段不要发布内容或启动容器。”	确保执行始终处于项目的实际边界之内
目标	“为两个代码库做好首次公开 alpha 发布的准备。”	让未来的工作能够围绕预期成果继续推进
未完成事项	“代码签名仍需由发布者保管。”	保留未完成的工作，不假装它已经完成
里程碑	“生命周期测试套件已在 PowerShell 5.1 和 7 中通过。”	连同来源信息一起传递经过验证的结果
偏好	“内部 RFC 保持本地，不公开。”	维持持久的项目惯例
事实或证据摘要	“打包的核心已禁用网络监听器。”	为回忆提供简洁、可追溯的技术依据

短暂的闲聊、猜测、复制的日志、机密，以及“也许有一天”之类的杂音，都不应成为持久记忆。当前的 Codex 模型会决定某项更改是否重要；宿主契约则限定了写入方式。

记忆如何增长

flowchart LR
    S[Session starts] --> R[Bounded candidate recall]
    R --> W[Codex works with current files]
    W --> C{Durable change?}
    C -- no --> W
    C -- yes --> Q[Quarantined candidate]
    Q --> G[Project / topic / memory DAG]
    G --> R
    Q -. explicit successor .-> Q2[New revision]

• SessionStart 会为新会话、恢复的会话、已清除的会话和已压缩的会话加载安全与连续性约定。
• UserPromptSubmit 会在提示词开始或实质性改变一项实质性工作区任务时，最多创建一次有界的回忆机会。
• 在工作期间以及循环安全的 Stop 检查点，Codex 可以自动记录重要决策、约束、偏好、目标、未完成事项和已验证的里程碑——无需特别念出“记住这个”之类的咒语。
• 稳定的项目、主题和记忆标识可让重试逐渐收敛。事实发生变化时，会明确创建后继记录，而不是悄无声息地覆盖先前记录。
• 多父级链接让一条记忆既可归属其项目或主题，也可连接到相关决策、目标或未完成事项。

这些钩子会提供自动记忆的机会和指令；它们不会把每个词元都变成永不消散的垃圾。Codex 要求你信任这些钩子时，请检查随附的钩子；安装或更新后，请开始一项新任务，以便宿主加载当前软件包。

旨在不轻信自身记忆

自动记录的内容是经过类型标注的候选项，不是权威事实。

model output → deterministic identity + policy checks → quarantined candidate
                                                     ↛ canonical memory

面向模型的 MCP 接口无法提升、更正、覆盖或删除规范语义记忆。在使用候选项之前，技能会将其实体化，遍历其层级结构，并验证路径是否指向当前检出版本的项目根目录。召回的内容仍是不可信数据：绝不会将其插入 shell 命令，也不会将其视为权威信息。

这种谨慎是有意为之。持久存在的幻觉，不过是长期留存的 Bug。

架构

flowchart LR
    subgraph Host[Codex host]
      H[Lifecycle hooks] --> K[ContextDB memory skill]
      K --> M[MCP tools]
    end
    M -->|stdio| P[Local MCP proxy]
    P --> B[Single-owner local broker]
    B --> D[(ContextDB native store)]
    D -->|authorized, bounded recall| M

打包的核心必须报告：

build_profile local-mcp
network_listeners disabled

启动器会拒绝不符合该配置的二进制文件。Windows 使用经过身份验证的命名管道代理和 CurrentUser DPAPI 保管机制；Linux 使用经过身份验证且仅所有者可访问的 Unix 域套接字、0700 目录、0600 密钥和状态头文件，以及 XDG 数据层级。Linux 文件权限并非透明加密：如果需要更强的静态数据保护，请使用操作系统的磁盘加密。可变保管数据存放在源代码检出目录和 Codex 版本化插件缓存之外。两种配置都不需要由发布方运营的后端、分析服务、云同步或 OpenAI API 密钥。

安装

从 Codex 市场安装

这是最精简的安装方式。它只需要一个公开仓库，不需要 ContextDB 源码检出目录。添加之前，请确认 node --version 显示 v18 或更高版本；Linux 还需要 python3 --version 显示 3.10 或更高版本。仓库安装程序会自动执行这些检查，而直接添加市场插件无法在 Codex 缓存插件之前运行代码。

codex plugin marketplace add mikhailbovt/ContextDB-Codex --ref v0.6.0-alpha.3
codex plugin add contextdb-memory@contextdb-codex

安装后，请开始一项新的 Codex 任务。首次启动 MCP 时，插件会检测宿主操作系统，下载由匹配平台锁文件固定的准确 ContextDB 核心 ZIP，并验证其规范 GitHub Release URL、字节长度、归档 SHA-256、安全 ZIP 布局、可执行文件 SHA-256、无监听器构建配置、目标平台 SBOM、依赖声明和 Rust 许可证。随后，它会初始化 Windows CurrentUser DPAPI 保管机制，或 Linux 仅所有者可访问的本地保管机制。可变记忆存储在版本化插件缓存之外。两个平台都要求 PATH 中有 x64 版本的 Node.js 18+，供市场 MCP 分发器使用；Linux 还需要 Python 3.10+，但不需要 PowerShell。两个平台都不需要 ContextDB 检出目录、Docker 或远程 MCP 服务。

从独立完整的发行包安装

每个平台都提供一个完整的发行 ZIP；无需下载第二个仓库或运行时。 从 Releases 中选择你的操作系统，验证对应的 .sha256 校验文件，然后在本地安装。

Linux x86-64：

archive=contextdb-codex-0.6.0-alpha.3-linux-x86_64.zip
sha256sum --check "$archive.sha256"
python3 -m zipfile -e "$archive" .
cd contextdb-codex-0.6.0-alpha.3-linux-x86_64
bash install.sh

install.sh 会验证随包附带的核心组件、平台锁定文件和供应链凭据，安装 Codex marketplace 和插件，并完成真实的 16 工具 MCP 握手。需要 Python 3.10+ 和 Codex CLI；PATH 中还必须有 x64 版 Node.js 18+，供跨平台 MCP 启动器使用。Python 的便携式 ZIP 解压器不会还原 Unix 可执行位；在所有随包凭据均匹配后，安装程序会通过禁止跟随符号链接的文件描述符，将不可执行的程序包 ELF 复制到单独的、仅所有者可访问的 0700 运行时 inode 中。程序包负载不会被修改权限或执行，因此，即使写入者保留了原始文件描述符，也无法更改已激活的运行时。预发布工作流会在隔离的 Codex 主目录中，通过标准解压流程重复这一精确步骤。

Windows x86-64：

$archive = (Resolve-Path .\contextdb-codex-0.6.0-alpha.3-windows-x86_64.zip).Path
$expected = ((Get-Content "$archive.sha256" -Raw).Trim() -split '\s+')[0].ToLowerInvariant()
$actual = (Get-FileHash -LiteralPath $archive -Algorithm SHA256).Hash.ToLowerInvariant()
if ($actual -ne $expected) { throw "Release checksum mismatch: $actual" }
Expand-Archive -LiteralPath $archive -DestinationPath .
Set-Location .\contextdb-codex-0.6.0-alpha.3-windows-x86_64
.\install.cmd

发行包已包含经过验证的 ContextDB 可执行文件、依赖项声明、CycloneDX SBOM、Rust 运行时许可证、生命周期脚本、插件和公开文档。安装程序运行时无需下载第二个仓库或运行时。PATH 中必须有 x64 版 Node.js 18+ 和 Codex CLI。

从源代码安装

常规预编译安装路径只需克隆此仓库。在 Linux 上：

git clone https://github.com/mikhailbovt/ContextDB-Codex.git
cd ContextDB-Codex
bash install.sh

在 Windows 上：

git clone https://github.com/mikhailbovt/ContextDB-Codex.git
Set-Location ContextDB-Codex
.\scripts\install.ps1

两个安装程序都会下载并验证各自固定版本的平台发行包。只有在开发或自行重新构建核心组件时，才需要相邻目录中的 ContextDB 仓库检出版本。Windows 开发者覆盖选项为：

.\scripts\install.ps1 -ContextDbRepo ..\ContextDB

仅在选择此可选的源代码构建路径时，才需要 Rust 1.97.1。

如有需要，请验证已安装的清单：

codex plugin list --json

完成任何安装后，请启动新的 Codex 任务，以便 Codex 加载当前的钩子和技能。

验证实现

在 Linux 上，运行隔离的原生生命周期和发行版检查：

python3 scripts/test-linux-lifecycle.py --help
python3 scripts/test-linux-release-install.py --help
python3 scripts/contextdb-linux-release.py --help
python3 docs/release/validate-publication-kit.py

在 Windows 上，确保两个仓库均可用，然后运行：

.\scripts\test-hooks.ps1
.\scripts\test-mcp.ps1
.\scripts\test-auto-hierarchy.ps1
.\scripts\test-custody.ps1 -ContextDbRepo ..\ContextDB
.\scripts\test-lifecycle.ps1 -ContextDbRepo ..\ContextDB
python .\docs\release\validate-publication-kit.py

两个平台的生命周期测试套件都会使用隔离的临时保管目录和隔离的 Codex 主目录，测试安装、MCP 启动、备份、还原、可恢复重置、marketplace 安装、自定义根目录清除、运行时清除和卸载。Linux 测试套件还会验证并发代理客户端，以及在维护前从仅所有者可访问的崩溃残留 Unix 套接字中恢复。Windows 发行版也继续兼容 Windows PowerShell 5.1 和 PowerShell 7。具体的证据范围请参阅支持矩阵。

备份、还原、重置和卸载

在 Linux 上，使用受保护的本地生命周期管理器：

python3 scripts/manage-linux.py backup --destination "$HOME/contextdb-memory.cdb-backup"
python3 scripts/manage-linux.py restore --backup "$HOME/contextdb-memory.cdb-backup"
python3 scripts/manage-linux.py reset --confirm RESET-CONTEXTDB-MEMORY
python3 scripts/manage-linux.py uninstall

只有通过单独的明确选择和精确确认，才会删除数据和不可变运行时：

python3 scripts/manage-linux.py uninstall \
  --remove-marketplace \
  --purge-data \
  --purge-runtime \
  --confirm DELETE-CONTEXTDB-MEMORY

在 Windows 上，将备份保存到实时保管目录之外的新路径：

.\scripts\backup.ps1 -Destination D:\Backups\contextdb-memory.cdb-backup

还原经过验证的复合备份：

.\scripts\restore.ps1 -Backup D:\Backups\contextdb-memory.cdb-backup

创建新的保管目录，同时将旧状态保留在带时间戳的恢复目录中：

.\scripts\reset.ps1 -ConfirmReset RESET-CONTEXTDB-MEMORY

仅移除已安装的插件：

.\scripts\uninstall.ps1

删除数据和不可变运行时需要单独的明确选择标记和精确的确认令牌：

.\scripts\uninstall.ps1 `
  -RemoveMarketplace `
  -PurgeData `
  -PurgeRuntime `
  -ConfirmPurge DELETE-CONTEXTDB-MEMORY

删除文件系统内容并不意味着可进行取证级安全擦除。备份和主机上的对话历史记录仍是单独的副本。

明确不作出的声明

此预览版不声称具备确定性的规范裁定、取证级彻底删除、KMS/HSM 保管、删除提供商副本、语义规模认证、Authenticode 签名、Linux 密钥文件加密、兼容 macOS/ARM64、云同步或托管式 MCP 端点。

文档和政策

• 文档索引
• 支持矩阵
• 本地 MCP 工具契约
• 本地验收用例
• 贡献指南
• 行为准则
• 安全政策
• 隐私声明
• 支持政策
• 条款
• 更新日志
• Apache-2.0 许可证

支持项目

如果这个插件让你不必再向健忘的机器人重复解释同一个架构决策，你可以通过 GitHub Sponsors 或 Ko-fi 支持开发。我们感谢赞助，但使用或获取支持都无需赞助。