hypermnesia-mcp

让 AI 编码 Agent 的记忆可供问责。
在不同会话之间保留决策、修复和项目上下文，并检查检索到的内容。
默认在本地运行。无需账户、API 密钥，也无需管理服务。

Sovereign 就是它如今的状态。 所有内容都在你的机器上运行：默认使用本地 SQLite 文件，也可按需使用 PostgreSQL + pgvector。检索流程中不使用大模型，除非你配置会将数据发往外部的集成，否则不会有任何内容离开 localhost。项目记忆是你拥有并可以删除的文件。

Claude Code 和 Codex 共用 Cortex 记忆。 两者的原生插件都提供相同的记忆工具和 11 个生命周期钩子模块，用于自动捕获、回忆和提供项目上下文。在项目中任选一种 Agent，切换时也能保留记忆。 已在 macOS 上通过真实的 Claude 和 Codex 会话验证。 同一个 stdio MCP 服务也会向 Claude Desktop、Claude Cowork 和其他本地 MCP 宿主提供记忆工具。

我们的目标是对生态负责。 无需进入数据中心的工作，就无需消耗能源供其运行；而能一次找到正确上下文的 Agent，也会少读一些文件。我们以 Green Software Foundation 的 SCI 方法为准，并且不公布 CO₂ 或能耗数据，因为我们尚未测量这些数据。 我们声称什么、不声称什么 ↓

36 种神经科学机制 · 57 个记忆工具 · 11 个生命周期钩子 · 每个项目一套自我整理的 wiki——全部本地运行、全部开源、采用 MIT 许可证。

安装

Claude Code — 添加市场并安装插件：

claude plugin marketplace add cdeust/Cortex
claude plugin install hypermnesia-mcp
claude --init-only

claude --init-only 会运行插件的 Setup 钩子，在首次会话开始前安装 Cortex 的运行环境（基础依赖、语义搜索及其嵌入模型）。安装成功或失败都不会输出任何内容，并且都会以 0 退出（Claude Code 会丢弃 Setup 钩子的输出）。若要查看进度并在失败时获取非零退出码，请改为运行已安装插件中的 scripts/init_plugin.py（其路径是 claude plugin list --json 中的 installPath）。

更新方式相同，只需运行一条命令，然后重新初始化：

claude plugin update hypermnesia-mcp
claude --init-only

Claude Desktop — 从 Releases下载 hypermnesia-mcp.mcpb 并打开，或使用 Settings → Extensions。该软件包包含工具，但不含钩子；MCPB 格式不支持钩子。

系统会自动检测 Claude Cowork（CLAUDE_ENVIRONMENT=cowork），并使用本地 SQLite 存储。无需 PostgreSQL。

对于 Codex，请安装原生插件以使用记忆工具和自动钩子：

uv tool install "hypermnesia-mcp[sqlite]"
codex plugin marketplace add cdeust/Cortex
codex plugin add hypermnesia-mcp-codex@cortex-codex-plugins

在 Codex 中打开 /hooks，检查并信任 Cortex hooks，然后启动新会话。更新后，变更过的 hook 定义需要重新获得信任。该插件使用与 Claude Code 相同的已保存后端选择；当两个宿主使用相同的配置根目录和存储时，它们会共享记忆。 Codex 设置详情。

其他 stdio MCP 宿主（Gemini CLI、Cursor、Windsurf、VS Code）会启动同一服务，并获取相同的工具。请参阅启动命令。 部署场景介绍了 WSL、TLS 客户端证书和企业代理。

Cortex 的依赖项位于插件的数据目录中，每组锁定的依赖项各占一个目录（sets/<key>），因此，如果更新未改变锁定的依赖项（大多数版本都如此：从 v4.9.0 到 v4.23.5 的 29 个版本中有 21 个），就能找到已安装的依赖项集。后台任务会移除没有已安装版本引用的依赖项集；它不会发起网络请求。如果依赖项集缺失（安装后的第一个会话，或更改了锁定依赖项的更新之后，且此前未运行 claude --init-only），则不会安装任何 hook：SessionStart 会提示 Cortex is installing its dependencies (about 2 minutes, about 5 with semantic search); memory is available when it is done，Edit/Write 防护会允许编辑，并提示 Cortex gate 在依赖项安装完成前处于非活动状态；MCP 服务会在后台安装依赖项集；下一个会话（或安装完成后的当前会话）会显示 Cortex ready: <store>, <n> memories; <how recall ranks>。claude --init-only（或会显示进度的 python3 scripts/init_plugin.py）会在第一个会话之前安装所有内容；只有使用此命令，首个会话才能启动时即处于就绪状态。无论是否离线，如需在不使用 Cortex 的情况下工作，请运行 claude plugin disable hypermnesia-mcp@cortex-plugins。

在 macOS 和 Linux（glibc）上，全新安装后运行 claude --init-only 还会为插件安装专属的 PostgreSQL 服务和 pgvector、pg_trgm：这些固定版本且经过 sha256 校验的二进制文件（约 13 MB；pgvector 由 Cortex 的 CI 编译，并附有构建来源证明）运行于 127.0.0.1，无需 Homebrew 或系统 PostgreSQL。其数据位于 ~/.claude/methodology/managed-pg/，因此卸载插件不会删除你的记忆。只有在该服务已启动且其架构已创建后，它才会成为存储；如果无法启动（例如 Linux 发行版缺少 libxml2.so.2 或 OpenSSL 3），就会使用 SQLite 存储，Windows 上也会使用 SQLite；会话启动时会说明原因（SQLite fallback: ...）。同一账户上的 Codex 插件会连接到同一服务。现有的 SQLite 存储不会迁移（ADR-1114）。

否则，首次使用时会在 ~/.claude/methodology/ 下创建本地 SQLite 存储。需要时会下载模型一次，之后便可离线运行。嵌入模型和重排模型文件都会在首次使用时下载。只有在明确配置后，可选集成、远程 PostgreSQL 和 OTLP 遥测才会使用网络。PRIVACY.md 列出了确切的范围。

现有 PostgreSQL 设置会予以保留：已配置的 database_url 选项（或 DATABASE_URL），以及 install-plugin.sh --postgres 写入的后端标记，始终优先于插件自带的服务和 SQLite 默认设置。如果此前在本地 cortex 数据库上运行过安装，且没有配置任何内容，则会保留该数据库：首次启动时，只有在 localhost:5432 上没有服务监听，且没有任何 PG* 变量配置 PostgreSQL 的情况下，Cortex 才会切换到 SQLite、记录此选择并打印提示。全新安装绝不会连接到未配置的数据库。

claude plugin uninstall cortex
claude plugin install hypermnesia-mcp

claude plugin uninstall cortex-viz@cortex-plugins
claude plugin marketplace update cortex-plugins
claude plugin install hypermnesia-mcp-viz@cortex-plugins

允许列表、钩子、技能和 Agent 必须迁移以下两个组合工具名称： mcp__plugin_cortex-viz_cortex-viz__open_visualization 变为 mcp__plugin_hypermnesia-mcp-viz_hypermnesia-mcp-viz__open_visualization，而 mcp__plugin_cortex-viz_cortex-viz__get_methodology_graph 变为 mcp__plugin_hypermnesia-mcp-viz_hypermnesia-mcp-viz__get_methodology_graph。

保持上下文有用

在不同会话中，Agent 需要记住决策，在类似问题再次出现时带回之前的修复，并向你展示哪些来源支撑某条记忆，以便你进行纠正。Cortex 会让这些上下文持续可用，同时让其状态清晰可见。

Cortex 通过本地质量检查实现这一点：写入了什么、引用是否有效、决策变更时会发生什么，以及哪些内容会随时间淡化。

哪些内容会被写入

写入内容会根据已有存储内容通过本地新颖性检查（实现中称为预测编码门控）。新内容会被写入；近似重复的内容会合并到其重述的记忆中，而不会另行存档。

// Illustrative project decision:
remember({ content: "Keep session state in Redis so TTL expiry is handled consistently." })
// → { stored: true, action: "stored" }

对于经过审慎决定的写入，即使内容并不新颖，也绝不会拒绝。无人值守的自动捕获则会被拒绝，这样自动捕获就不会淹没你想要保留的记忆。

内容是否可核查

每条记忆都会在写入时于本地评级，不会发起网络调用。这个评级不是置信度分数，而是判断其中的主张是否带有能在此计算机上解析的引用。

// → provenance: { grade: "unverifiable",
//                 reason: "dead_refs: deps/numpy/_core/_multiarray_umath.cpython-313-darwin.so",
//                 hint: "1 of 9 checkable reference(s) could not be resolved" }

这条记忆引用了一个已不存在的文件，因此它仍被存储，但被标记为 unverifiable，而不是悄然呈现为已验证状态。若根据可解析的路径重写，同一条记忆就会被评为 verified。回忆出的记忆会告知你它属于哪种状态；verified 评级仍只表示引用能在本地解析，并不意味着该主张已得到独立证实。

发现内容有误时

更正会取代原内容，而不是将其覆盖。新记忆会记录它取代的内容，旧记忆在回忆中的优先级会降低，同时更正链仍保持可读。

remember({ content: "...", supersedes_id: 4360411 })
// → { action: "superseded", memory_id: 4360412, superseded_id: 4360411 }

内容是否正确

记忆记录发生过什么。预测记录的是结果尚未揭晓时的预期，以便 Cortex 之后能发现预测有误。predict 会写入一条可证伪的主张，并记录当时的置信度；resolve_prediction 会根据调用方提供的观察结果进行判定，记录判决、作出判定的来源类型，以及指向该来源的引用；calibration 则会为已判定的预测集评分。

predict({ claim: "The p90 of the SQLite job is under 6 minutes",
          prediction: "a 20-minute budget leaves headroom", test: "21 attempts of 2026-09-16",
          confidence: 0.8 })
// → { prediction_id: 12, status: "open" }
resolve_prediction({ prediction_id: 12, verdict: "confirmed",
                     observed: "p90 348 s over 18 successes",
                     source_kind: "ci", source_ref: "cdeust/Cortex actions, 2026-09-16" })
// → { prediction_id: 12, verdict: "confirmed", resolved: true }
calibration()
// → { scored: 9, brier: 0.11, uninformative_brier: 0.25, confirmed: 7, refuted: 2,
//     reliability: [{ band: [0.6, 0.8], resolved: 4, mean_confidence: 0.78,
//                     observed_frequency: 0.75 }, ...] }

brier 是置信度与结果之间的平均平方距离；恒定的 0.5 预测会得到 0.25，因此高于该分数意味着这些置信度所携带的信息还不如什么都不说。Cortex 不会自行获取证据：判决、观察结果和来源引用都由调用方提供，因此同一套约定适用于任何仓库和任何审查惯例。

哪些内容会淡化

记忆会携带随时间衰减的热度，除非通过重播加以强化；情景痕迹也可以巩固为语义记忆。一次具体的调试过程可能会浓缩为它所揭示的原则；命令或许会淡化，但经验教训会保留下来。这一生命周期旨在让存储内容随着增长仍然有用，但不承诺存储大小固定，也不保证一定会进行语义压缩。

使用体验

以下是一个示例工作流：决策、此前的修复方案和源代码检查再次发挥作用。

星期一。 花了一小时调试 webhook 处理程序，最后发现是竞态条件：TTL 在身份验证检查与权限查询之间过期。你们商定修复方案，完成实现，然后结束会话。

星期四。 在另一个会话中，用户报告会间歇性退出登录。新工作的内容与此前内容匹配时，Cortex 会呈现相关的先前分析、Redis 决策以及 TTL 经验。

三周后。 这些会话可以归纳成一个关于身份验证和基于 TTL 的缓存的模式；一些细节可能会淡去，但原则仍然有用。

在 Claude Code 和 Codex 中，这一切都是自动的：11 个生命周期钩子会在会话开始时注入上下文、按提示词检索、在工作过程中捕获信息、在压缩前创建检查点，并运行一个能够自我整理的 wiki。在其他任何 stdio MCP 主机中，你都可以自行调用同样的 57 个工具；如果存在可选的 ai-architect-mcp-codebase 和 ai-architect-mcp-spec 集成，则有 60 个工具。

检索效果如何

仅依据已发布的基准测试衡量检索效果。流程中不使用 LLM 阅读器：我们关注的是能否检索到正确的记忆，而不是模型能否据此写出好的答案。

LongMemEval：500 个由人工整理的问题，埋藏在约 40 个历史会话中。

两者都只运行了一次：n=500，数据库干净，停用归并，仅进行检索。

v4.14.1，2026-07-14：产物 JSON； 代码 SHA。 验证中的消融实验就是围绕这次运行构建的。

v4.20.0，2026-09-09：产物 JSON及其 清单；代码 SHA， dirty=false。在隔离的临时 PostgreSQL 容器中，仅运行一次 LongMemEval-S 测试（benchmarks/reproduce.sh --only longmemeval --no-ablation），加载重排器，停用归并。与 v4.14.1 相比，Recall@10 下降 0.4 个百分点，MRR 下降 0.012。该次运行的下限检查报告，Recall@10 与 7 月下限（0.982）的差距在 0.005 容差范围内，而 MRR 比其下限（0.914）低 0.0093；按设计，脚本将此情况视为非阻断项； docs/agent-guidance.md 记录了 main 已无法达到这些下限，发布门槛则是相对于 origin/main 执行 --no-regression。同一代码树尚无 LoCoMo 或 BEAM 的结果。

使用 benchmarks/reproduce.sh 复现。它会在隔离的临时容器中运行，不会针对正在使用的数据存储运行。

Recall@10 表示答案所在会话出现在检索结果前十个会话中的问题占比。MRR（平均倒数排名）用于衡量该会话是否出现在靠前位置。这些数值仅反映检索效果，不衡量 LLM 能否写出正确答案。

检索会融合向量相似度、全文搜索、三元组匹配、热度和时效性，然后使用交叉编码器进行重排。PostgreSQL 会将这些信号合并为加权和；SQLite 使用加权倒数排名融合，且不包含三元组信号。LoCoMo 和 BEAM 的结果、消融实验以及下限门槛见 benchmarks/。

存储

默认使用 SQLite；在全新的 macOS 或 Linux 安装中，也可以使用插件自带的 PostgreSQL 服务（参见 Install）。使用你自己的 PostgreSQL 只需配置一个字段，对于超大型存储或团队共享数据库来说值得一试。

bash <plugin-dir>/scripts/install-plugin.sh --postgres

三个钩子增强功能仅支持 PostgreSQL，在 SQLite 上会静默地降级为无操作。会话横幅、自动召回、自动捕获、检查点和每个记忆工具都可在两者上运行。

在 Codex 和 Claude Code 中使用 Cortex

两个插件都提供完整的记忆工具配置，并使用相同的 11 个 Cortex 钩子模块。如果连接到同一存储，它们会共享与项目关联的记忆，因此在 Claude 中保存的决策可在 Codex 中召回，反之亦然。

安装原生 Codex 插件并信任其钩子后，Cortex 将：

• 在会话开始时恢复项目上下文，并在你提交提示词时召回相关记忆。
• 自动捕获重要的工具结果，让有用的工作内容在不同会话间保留。
• 通过压缩检查点和持久化的会话结束记录保留会话状态。
• 为子 Agent 提供项目和角色上下文。
• 提供完整的记忆工具集，用于决策、经验教训、维基页面、ADR、预测、校准、触发器、规则和代码库摄取。
• 在 Claude Code 与 Codex 使用相同存储和项目关联时共享记忆。你可以切换 Agent 并检索另一个 Agent 保存的内容。

Claude Code 使用相同的 Cortex 记忆工具和钩子模块。两个插件都支持自主维基循环、SQLite 存储和可选的 PostgreSQL。

**已在已安装的主机上验证：**Claude 写入了一个随机测试负载，Codex 成功检索；Codex 又写入另一个负载，新的 Claude 会话成功检索。两边都没有读取提示词中提供的预期负载。从另一个项目召回时，两个主机都排除了测试记录，并且都通过原生启动钩子提供了 Cortex 上下文。查看验证结果和工具调用记录。

钩子信任是 Codex 设置的一部分：安装后或钩子定义变更后，请检查 /hooks，然后启动一个新会话。事件映射、任务上下文处理和会话结束时的内容交付详见 Codex 集成指南。 认知配置也会共享；当前的配置构建器会从 Claude Code 会话日志中推导配置，因此，要让任一主机检索到已填充的配置，都必须存在这些历史输入。

其他 MCP 宿主

任何能够启动 stdio 服务的宿主都能使用完整的记忆工具配置，默认使用 SQLite，也可选择 PostgreSQL。直接注册 MCP（包括 codex mcp add）会提供显式的 remember 和 recall 工具。原生 Claude Code 或 Codex 插件还具备自动生命周期行为。Claude Desktop 套件提供工具，但不含钩子。ChatGPT 网页版需要远程部署；此仓库提供的是本地 stdio 服务。

所有宿主的启动命令都使用 PyPI 软件包。[sqlite] extra 可启用 sqlite-vec 向量搜索；不安装时，存储仍可用，但会禁用向量搜索。

uvx --from "hypermnesia-mcp[sqlite]" hypermnesia-mcp

Gemini CLI 以扩展形式提供（此仓库中包含 gemini-extension.json）：

gemini extensions install https://github.com/cdeust/Cortex

Codex 和 ChatGPT 桌面版 提供原生插件，具备完整的工具功能，以及 Claude Code 插件安装的相同 11 个生命周期钩子。它会读取与 Claude Code 启动器相同的已保存后端选择（~/.claude/methodology/backend.json），因此两个宿主会写入同一个存储（自 4.23.0 起）；但显式设置的 CORTEX_MEMORY_STORE_BACKEND、CORTEX_BACKEND 或数据库 URL 优先。请先安装一次软件包，这样插件首次通过 uvx 握手时会复用本地 uv 缓存，而不必耗费启动时间下载 Python 环境：

uv tool install "hypermnesia-mcp[sqlite]"
codex plugin marketplace add cdeust/Cortex
codex plugin add hypermnesia-mcp-codex@cortex-codex-plugins

直接回退方案无需插件即可注册可执行文件：

codex mcp add cortex --env CORTEX_MEMORY_STORE_BACKEND=sqlite -- hypermnesia-mcp

docs/codex-plugin.md 介绍了宿主边界、经测量的启动上限，以及 Cortex 刻意不声称满足的公开目录要求。

绿色软件工程

Cortex 持续开展效率计划，并遵循与检索工作相同的证据规则：未经来源支持的效率声明绝不发布。 浪费会被视为缺陷，并要求提供复现步骤，而不是值得宣传的优点。

测量工具——以及它无法证明的内容

benchmarks/energy/ 实现了 Green Software Foundation SCI 规范：运行排放量 O = E × I，隐含排放分摊 M = TE × TS × RS，并按功能单位报告。对于嵌入路径，功能单位是 1000 个模型输入 token， 根据分词器自身的 attention_mask 计数——绝不根据字符数估算。

引用其中的任何内容之前，请先阅读 benchmarks/energy/README.md。其中第一段最重要：自动化测试夹具会测试算术运算 和故障路径，但不会测量设备能耗，也无法证明能效有所提升。 此外，设计上还有以下限制：

• 没有默认碳排放系数。 --carbon-intensity（gCO2eq/kWh）和 --embodied（gCO2eq/s，已经分摊的费率）必须由操作人员提供，并会在导入任何模型前进行验证。工具会记录这些数值及其单位，但不会核实其来源。区域、观测周期、生命周期评估和预留假设均由你提供。
• 明确的测量边界。 raw_system_energy_j 是传感器对 CPU+GPU+ANE 的综合估算值。它既不是墙上插座测得的能耗，也不是完整的设备 SCI 评分：内存、存储、屏幕、电源损耗、模型预热和 token 计数均不在其中。
• 没有产物就不算完成。 成功运行会保留 results.json、记录提交版本和源代码哈希的 MANIFEST.json，以及经过分析的 powermetrics.txt 原始快照。

现在，真实基准测试运行的能耗测量结果已提交到 benchmarks/results/energy/，每份结果都包含原始 powermetrics.txt、阶段时间线和清单。已提交的数值仅代表某位操作人员在其机器、所在区域和运行周期下的一次测量，并非软件本身的固有属性；引用时必须始终注明这些限制：按查询计算的全程数值是一个上限（其中包含数据摄取、嵌入和数据库操作），不声称模型侧消耗了任何能量，而碳排放强度是操作人员提供并注明来源的输入值。请参阅 benchmarks/energy/README.md 中的 基准测试阶段。

实际已交付内容

效率改进通过常规审核 PR 落地。两个工作流已合并：

钩子相关工作是关键所在，因为每次工具事件都会触发钩子。 延迟加载处理器和存储层依赖，使钩子启动时间保持在 约 0.05 秒，而完整注册表导入需要 约 0.6 秒（测量日期为 2026-07-28；根据不虚构常量的规则，该常量在 mcp_server/hooks/auto_recall.py 的调用位置引用）。

减少需求是首要杠杆

大模型辅助工作流中，最大的效率开销并非本服务自身的 CPU，而是由于第一次未能找到合适的上下文，模型必须处理的 token。这意味着检索质量也关乎能耗，因此上文的基准测试表和本节属于同一项计划： response_budget.py 会限制负载并保留 ID，让截断后的内容仍可续传；重排器会退化为使用第一阶段的分数，而非获取模型；CORTEX_RERANKER_OFFLINE=1 则会直接拒绝下载。

这段话是设计依据，并非测量结果。Cortex 不会公布端到端 Agent 会话的 token 节省量或 CO2 数值，因为尚未对此进行测量。

验证

上述 v4.14.1 数据有逐机制消融测试支持——完整 n、单种子，并保留代码 SHA、脏标记、清单和逐行 JSON；v4.20.0 数据则来自单次测量，且没有这些记录：

• LongMemEval-S，17 行，n=500 — docs/benchmarks/e1-v3-results.md。经校准的平衡态下，各机制的差值及类别专门化分析。
• LoCoMo，14 行，n=1986 — docs/benchmarks/e1-v3-locomo-results.md（修复前）和 docs/benchmarks/e1-v3-locomo-results-post-fix.md（修复塑性结果形状问题后）。采用双基线设计（NO_CONSOLIDATION / WITH_CONSOLIDATION）。

逐机制的完整证据见热力学论文（§6.3）；BEAM 衰减剂量－响应分析（§6.4）记录了一项重新界定范围的负面结果，起因是发现并追查到脏存储造成的混杂因素。热力学记忆与扁平重要性存储（PDF，34 页） · 阶段感知上下文组装（PDF，39 页）。

内部机制

上述机制由 36 种系统机制实现，涵盖编码、巩固、检索和遗忘。每种机制都有已发表的研究作为依据，并作为实时系统指标公开。 参考文献 是核验依据：其条目数量就是引用数徽章显示的值，如果两者不一致，构建门禁就会失败。

整洁架构采用同心层：server → handlers → core ← shared，以及 infrastructure → shared。Core 是纯粹的，无需模拟对象即可测试。 docs/agent-guidance.md 是架构地图； docs/mcp-tools.md 是工具参考。

Claude 的记忆去向 追踪一条记忆从捕获它的钩子到让它重现的召回过程，也追踪一项决策从其 ADR 文件到读取它的会话；每项论述都链接到 v4.22.0 版本的对应行（法语版）。

安装前值得了解的限制

• 自动捕获和上下文注入由原生 Claude Code 和 Codex 插件提供。直接连接 MCP 时，需使用显式记忆工具。
• SQLite 融合在进程内进行，且未建立索引。个人规模下够用，规模非常大时会更慢。
• 上述检索分数仅衡量检索效果，与答案质量无关。
• 来源评级在本地进行，依据结构检查。它会检查引用是否能解析，而非论断是否属实；DOI 或 arXiv 链接绝不会自动验证。
• 出于上述原因，我们不会公布能耗或碳排放数据。
• 首次使用时会下载嵌入模型和重排模型文件。仅当明确配置后，可选集成、远程 PostgreSQL 和 OTLP 遥测才会产生网络活动；详见 PRIVACY.md。

安全

100% 在本地运行——MCP 通过 stdio 通信，存储后端（SQLite 文件或 localhost 上的 PostgreSQL）不会离开你的设备（可选的 hypermnesia-mcp-viz 配套工具会将其服务绑定到 127.0.0.1）。不会有任何数据离开你的设备。SafeSkill 扫描：94/100（代码 97，内容 88——docs/safeskill-report.json）。

隐私政策

Cortex 以本地为先：你的记忆、对话和个人资料都保留在你的设备上——默认存储在本地 SQLite 数据库（~/.claude/methodology/memory.db）中，也可存储在由你控制的 PostgreSQL 数据库中。Cortex 不会向作者、Anthropic 或任何第三方发送记忆、内容或遥测数据。唯一的外发网络活动是一次性从 Hugging Face 下载开源嵌入模型和重排模型（仅模型文件），以及你明确配置的任何集成。完整政策：PRIVACY.md。

支持

• 问题与 Bug 报告： GitHub Issues
• 安全问题披露： 详见 SECURITY.md
• 联系： [email protected]

开发

pytest                                # full suite; assets/badge-tests.svg carries the current count
ruff check . && ruff format --check . # lint and format, both enforced in CI
python scripts/check_doc_claims.py    # advertised counts must match the repo
python scripts/check_craftsmanship.py # file and method caps, layer whitelist, sourced constants

CONTRIBUTING.md 说明变更必须通过哪些门禁。 GOVERNANCE.md 说明由谁决策，以及维护者停止维护时会如何处理。 docs/ROADMAP.md 说明项目的发展方向， docs/ASSURANCE-CASE.md 阐述安全论证及其局限。 CHANGELOG.md 是完整的版本发布历史。

许可证

MIT — 参见 LICENSE。

本软件由 Clément Deust 独立开发，属于其个人作品。它是在任何雇佣关系之外开发的，与任何过去或现在的雇主均无关联、未获其认可，也不归其所有。本项目属于 ai-architect 生态系统的一部分 (zetetic-team-subagents、 ai-architect-mcp-codebase、 ai-architect-mcp-spec)。

本软件中编码实现的神经科学和信息检索算法源自已发表的学术研究，相关引用见 docs/papers/bibliography.md，源代码中也通过 # source: 注释标明（Friston 关于预测编码的研究、Anderson 和 Lebiere 关于率失真遗忘的研究、Nader 等人关于检索诱发的不稳定性的研究、McClelland 等人关于巩固的研究，以及其他研究）。MIT 许可证适用于本实现；它不主张对底层机制的所有权，这些机制的归属仍应属于其原作者及相关出版物。

引用

main 分支上的论文 PDF 是规范版本（arXiv 编号即将公布，背书正在进行中）：

@software{cortex2026,
  title={Cortex: Persistent Memory for Claude Code},
  author={Deust, Clement},
  year={2026},
  url={https://github.com/cdeust/Cortex}
}

@unpublished{deust2026thermodynamic,
  title={Thermodynamic Memory vs. Flat-Importance Stores:
         Why Long-Term Retrieval Collapses Without Decay},
  author={Deust, Clement},
  year={2026},
  note={arXiv ID forthcoming, endorsement in progress},
  url={https://github.com/cdeust/Cortex/blob/main/docs/arxiv-thermodynamic/main.pdf}
}

@unpublished{deust2026context,
  title={Stage-Aware Context Assembly for Long-Context Memory Retrieval},
  author={Deust, Clement},
  year={2026},
  note={arXiv ID forthcoming, endorsement in progress},
  url={https://github.com/cdeust/Cortex/blob/main/docs/arxiv-context-assembly/main.pdf}
}