codex-memory
Allows exporting project knowledge (code map, baseline, and README links) to an Obsidian vault for human-readable reference.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
共享项目库
多智能体共用的项目状态控制平面。 不同 AI 会话之间不共享聊天记录,只共享结构化结论——谁在做什么、做到哪、踩过什么坑、代码长什么样。

它解决什么问题
一个 AI 会话的上下文是临时的,一关就没了。多个会话要接力做一个项目时,传统做法是把聊天记录复制来复制去—— 既费 token 又不准确,而且"踩过的坑"永远传不下去。
这个库把项目状态放在会话之外:新会话一进来读一次库,就知道前面发生了什么、现在该干什么、哪里是雷区。
Related MCP server: samskriti-project
两个消费者,一份事实来源
flowchart LR
PG[(PostgreSQL<br/>唯一事实来源)]
AI[AI 会话们<br/>读结构化数据]
YOU[你<br/>看极简进度]
PANEL[悬浮球面板]
PG -->|MCP 工具| AI
AI -->|写结论| PG
PG -->|SSE 毫秒推送| PANEL
PANEL --> YOU
YOU -.->|复制接续块| AI消费者 | 看到什么 | 怎么用 |
AI 会话 | 任务合同、检查点、踩过的坑、代码地图、决策、交接 | MCP 工具读写( |
人 | 项目名 · 状态 · | 悬浮球面板:点任务复制一句自带指令的文本 |
核心概念
概念 | 是什么 |
Project | 一个项目(有 root_path、隔离的数据域) |
Task | 可领取的工作单元(有合同、依赖、租约、负责人) |
Contract | 任务的验收标准(干成什么样算完) |
Checkpoint | 我干完了什么 / 没干什么 / 踩过什么坑 / 下一步 |
Code Map | 代码的结构化地图(模块、职责、调用关系、新不新鲜) |
Artifact | 真实产出的文件(只声明路径不算,对账会判 rejected) |
Handoff / Reconciliation | 交接说明 / 独立对账结论 |
English — A project state control plane shared by multiple AI agent sessions. Sessions don't share chat logs; they share structured conclusions: what's being worked on, what's done, which pitfalls were hit, and what the code looks like. One source of truth (PostgreSQL), two consumers: agents read structured data via MCP tools, humans watch a minimal progress panel (shared-lib-panel).
See docs/SETUP.md to get it running.
配套面板(另一个仓库)
shared-lib-panel —— 悬浮球形态的进度面板:
开机 | 点开 | 任务级 |
|
|
|
ℹ️ 上面三张是用面板自己的渲染函数 + 自己的样式表画出来的(含真引擎出的球), 项目数据是编的(不是真项目)—— 结构、配色、字号就是面板真实的样子。
面板只读:它不写库,只负责「复制一段指令给你粘给 AI」;AI 干完写库,面板通过 SSE 自己刷新。 角落那颗球本身也有反馈:库里发生事它动一下、整体状况(有活在跑/有卡住/全闲)变化时它的呼吸和视线跟着变。
快速开始
git clone https://github.com/Paeonia-wh/codex-memory.git
cd codex-memory/repo
./scripts/start-memoryd-silent.ps1 # 起 PostgreSQL + memoryd(手工排障用)
# ⚠ 不要用 scripts/start-services.ps1 —— 它**已废弃**:
# 它走 pg_ctl(会拉起一个终端窗口),而且传参不对会**静默失败**
# (实测在 pg-silent.err.log 里留下过 "pg_ctl: 命令行参数太多")。
# 开机自启走 scripts/autostart.pyw(计划任务 CodexMemoryAutostart 调用它)。环境搭建见 docs/SETUP.md;给 AI 会话看的用法见下方。
平台内部:多智能体项目知识与状态平台
上面那半是给使用者的(它是什么、怎么跑起来)。 从这里往下是开发者文档 —— 实现细节、工具清单、写入边界、体检机制。
供 Codex 与 DeepSeek 多会话共享的本地项目知识、任务状态和证据服务。运行目录固定在 D:\codex-memory;原始文件只读,凭据不会进入 Git。
用户手册在
D:\codex-memory\README.md—— 讲这是什么、别的会话怎么用、以及怎么把一个已有项目迁进来。
第一版核心模型:
一个项目可以注册多个 Codex/DeepSeek 会话;每个会话独立领取任务,但共享 PostgreSQL 项目状态。
Project、Task、Session、Run、Checkpoint、Event、Artifact、Decision、Handoff 都带项目边界和来源。
Obsidian 只是 D 盘上的人类可读派生投影;PostgreSQL 是协调状态源,MCP 是 Agent 入口。
会话上下文是临时的;任务状态、检查点、决策和交付物是可恢复的长期状态。
运行
项目使用 D 盘独立 Python 3.12 环境。scripts/bootstrap.ps1 设置进程缓存后安装环境;scripts/run.ps1 启动本地服务。依赖版本由安装完成后的锁定清单记录。
对话使用(0.2)
本产品没有网页。通过Codex说“列出待确认记忆”“解释这条记忆”“确认/拒绝这条”“纠正它”“设置两天后过期”或“预览知识库清理”即可使用相应MCP工具。确认以你批准的具体内容为准;算法反馈不能替你确认。
同作用域、同类型的相同内容会去重;候选默认30天过期,每作用域最多200候选、2000活动记忆。运行数据采用50GiB写入预算,另保留D盘100GiB余量。知识不足或预算不足会显式报告。
清理默认仅预览,应用前自动创建加密备份;删除失效向量及30天以上未被引用的非活动文本块。原文件、记忆和检查点不在清理目标内。此版本不宣称自动学习模型参数或完整语义纠错。
共享项目库使用
这里的“共享项目库”指项目协作状态本身:项目、任务、合同、会话、检查点、产物、交接、决策和代码地图。 它和资料检索/证据 catalog 是两套边界:资料不会因为被检索到就变成项目事实,项目会话也不能把聊天原文或私有推理直接写进项目状态。
项目状态通过 project_bootstrap、project_create、project_for_path、project_baseline_capture、project_session_register、project_sessions、project_task_create、project_task_contract、project_task_claim、project_ready_tasks、project_task_dispatch、project_task_assign、project_lease_sweep、project_workspace_register、project_workspace_create、project_workspace_release、project_artifact_publish、project_context_pack、project_checkpoint、project_session_heartbeat、project_handoff、project_reconcile、project_plan_propose、project_plan_review、project_control_set、project_run_step_start、project_run_step_finish、project_overview、memory_primary_status、memory_primary_set 和 project_export_obsidian 管理。第一版只允许 codex 和 deepseek 两类会话;同一类模型可以注册多个会话。
项目登记后可调用 project_baseline_capture 保存低基数基线:代码根目录、Git 分支、HEAD、工作树是否干净、变更文件数量,以及共享状态对象数量。它只记录数量,不写入文件名、凭据或聊天内容。project_code_map_write 可附带 Git commit SHA;读取代码地图时会返回最近地图版本和更新时间。
迁入带 root_path 的代码项目时,name 是给用户看的显示名称,必须包含中文(例如“农业局项目”);project_key、任务键和会话标签不受此限制,供不同 AI 或不同会话内部命名。任务进入 done、failed 或 cancelled 后,服务会自动捕获基线、刷新 D 盘投影并记录 task_auto_synced,不需要用户额外提醒。终态检查点只在「该任务一条检查点都没有」时才会自动补一条空壳 —— 已经有检查点就不再补(所以「标 done 一定会有检查点」是错的;真正记录过程的是会话自己写的检查点,见下面「会话级写入边界」)。
索引维护先调用 memory_source_scope_audit 查看作用域污染,再用 memory_source_scope_reconcile(dry_run=true) 预览。确认后才用 dry_run=false:它会停用越界来源、修正历史会话作用域、重标记向量并清理陈旧派生向量,但不会删除原始文件。
正式来源 allowlist 保存在 D:\\codex-memory\\data\\sources.json;每个项目必须使用独立 source root/scope,禁止把整个 D:\\codex 作为某一个业务项目的来源。
project_export_obsidian 会在项目投影中生成 CODE_MAP.md 和 BASELINE.md,并从项目 README.md 链接到它们。PostgreSQL 仍是事实源,投影可以删除后重建。
project_task_dispatch 有两种语义:传 task_key 时精确领取那一个任务(多个 worker 各领各的模块,不会抢同一个队列);不传时先领指派给自己的任务,再领无人认领的,但绝不抢占租约仍然有效的任务。⚠ 三种情况下「不抢」不成立:① 对方的租约已过期(那是设计如此,租约过期即回收);② 任务处于 blocked/review 且无人持有(那时谁都能接手,包括你知道 task_key 直接指定);③ assignee_label 指向一个不存在的会话名时,预留视为失效、任务回到自由队列。project_task_assign 负责建立这种预留,project_sessions 让总控看见已经注册的执行会话及其 session ID。
memory_search 的 hybrid 默认走全文和向量召回;需要图片/截图相似度时显式传 visual=true,避免普通文本问题加载图像模型。
带标注问题集时使用 memory_evaluate 或 scripts/evaluate.py 生成 Recall、引用定位和声明支持率报告;没有标注时系统返回 not_configured。
DeepSeek Harness 的自定义 profile 还注册了 codex_memory_tool。因此只使用 DeepSeek 时,它可以直接调用共享平台的项目、任务、Checkpoint、Artifact、Context Pack 和交接工具;该桥现在已开放创建任务、计划提案与复核、任务指派、补记已完成任务(project_task_reopen)——不开放这些会让会话「平台内无路可走」而只能改数据库(实测发生过)。仍不开放:验收对账的最终裁定、架构图导出、投影写入、强制释放工作区等高风险动作。已领取任务的 DeepSeek 会话可以补充自己任务的合同、记录绑定任务的决策、提交待验收对账,以及合并自己的代码地图片段;这些写入受服务端会话/任务归属校验保护。唯一例外是用户明确从该入口新建项目时使用一次 project_bootstrap;bootstrap 会一次性写入有界初始计划,随后锁定结构化计划。
结构化计划变更不能直接覆盖:会话先用 project_plan_propose 写待审提案,审核会话用 project_plan_review 以 plan_version compare-and-swap 提交或拒绝。project_control_set 可以暂停或归档项目而不删除状态;暂停时不能领取任务、启动运行或创建工作区。运行中的副作用步骤使用 project_run_step_start/finish,成功步骤重试会复用结果。
Codex MCP 工具会从 FastMCP 连接 Context 自动生成项目级 session principal,并在第一次写入前登记会话,减少模型手填 session ID 的误用。计划审批的本地 loopback 面板由 scripts/project_review_panel.py 提供,浏览器不接触 memoryd service token。
会话级写入边界
每个 Codex 或 DeepSeek 会话实例都是独立主体;不能只按模型类型判断权限。同一个模型的不同会话也必须各自领取任务、续租和写自己的检查点。
检查点只允许任务的 owner 写,且任务必须处于
running/review。(这条现在是服务端硬门禁:非 owner 写入会收到PermissionError。审计实测过 24 条越权写入 —— 一个任务被别的会话写了 9 条,而检查点是项目摘要喂给每个新会话的唯一状态来源,所以这道门是必需的。)代码地图写入要求在这个项目里干过(拥有任务,或近 7 天内有过检查点/事件);整张
replace=true重写不是普通 worker 操作。合同和决策必须记录创建会话;
verified对账必须由不是任务负责人的独立会话完成。DeepSeek 桥默认不开放架构图导出、Obsidian 投影和项目
AGENTS.md写入;架构图只在用户明确要求时由受控会话生成。租约默认 15 分钟(
project_session_heartbeat可续,最长 24 小时)。过期后project_lease_sweep会把running任务退回pending并复位会话。但它对blocked/review不适用 —— 那两类由「孤儿回收」处理:无主且卡在非终态超过 24 小时才回队列;另外声称working但心跳超过 2 小时没动的会话会被回落到idle并释放任务。终态自动同步会记录代码地图新鲜度:
fresh、stale、unversioned或missing。地图不新鲜时,交接投影和 Context Pack 会明确警告,不能把它当作当前架构事实。说明书是行为提示,不是安全边界;真正的拒绝在共享服务端执行。
任务合同、工作区、产物、Checkpoint 和对账记录进入共享状态。产物登记的是路径,而文件可能被归档/移动/改写 —— 所以后台每 60 秒复检一遍,把每个产出的状态推进到终态:produced(在)/ missing(文件没了)/ drifted(文件还在但内容变了 —— 靠发布时记的 SHA-256 判)。Context Pack 里不可信的产出会带 [MISSING] / [DRIFTED] 标记,别拿它当证据(实测 54 条产出里 21 条指向的不是文件)。此外:完整聊天记录、私有推理和未发布文件不会自动进入共享层。每次 project_context_pack 都会同时返回项目摘要和结构化代码地图(节点、边、版本、新鲜度),因此接力会话会先读代码地图再进入任务;地图为 stale、unversioned 或 missing 时必须先核对,不能当成当前架构事实。remote-approved 是唯一允许进入远程模型 Context Pack 的产物可见性。project_deepseek_run 只连接本地 DeepSeek Harness /chat,不会回退到直接 API。
项目状态和生产证据 catalog 都使用 D 盘本机 PostgreSQL 的独立 codex_memory 数据库;连接由 CODEX_MEMORY_DATABASE_URL 指定,catalog 可用 CODEX_MEMORY_CATALOG_DATABASE_URL 覆盖。首次切换会保留并迁移 D:\codex-memory\data\catalog.sqlite,不会删除原文件。Obsidian 投影写入 D:\codex-memory\vault\projects,可随时删除后从 PostgreSQL 重建。
平台自己的体检机制(不变量)
这一整轮修的问题几乎都是同一个病:守卫写在了错误的一层。三个真实例子:
_why_not_claimable()是个只读的排障提示,可它在"说"任务不可领 —— 而真正决定能不能领的是claim_task()。两者一度互相矛盾。daemon 的写入门禁里有"任务 owner 不能自批对账"的守卫,而 store 层的
reconcile()没有 —— 直接调 store 就绕过了。reap_expired_leases的 WHERE 只匹配status='running', 于是blocked+ 无租约的任务永远清不掉(实测挂过 23 小时)。
共同点:规则写在了「提示」里、「门」里、或某一条 SQL 里,而不是被守卫的操作本身。
codex_memory/invariants.py 给每条不变量标注由哪一层强制:
| 含义 | 可信度 |
| 数据库约束 | 最强,绕不过 |
| 数据库触发器 | 强 |
| 应用层写入路径(store 方法里的校验) | 中,绕过 store 就没 |
| 只写在提示词/文档里 | 最弱,实际没人守 |
每条除了声明层,还带一条可执行的只读 SQL 检查(查出违规行数,0 = 通过)。 于是它有两个用途:
运行时哨兵:daemon 后台每 60 秒跑一遍,有违规记
invariant_violated事件CI 断言:
python scripts/check_invariants.py(退出码非 0 即拦下)
基线机制:规则是新加的,而库里已经有规则之前写的行。
每条不变量可以带 baseline(已知历史欠账条数)——
违规数 ≤ baseline 报"历史欠账"(不拦 CI),超出才是"新违规"(失败)。
这样既诚实(欠账一直看得见)又可用(新问题会红)。
baseline 只许调小,不许调大,和 prompt_only 的纪律一样。
随手查:project_invariants 工具返回登记册摘要 + 当前所有违规。
交付与验收
详见 docs/archive/PLAN.md 和 docs/archive/STATUS.md(这两份已归档;当前状态以 project_overview 与 project_invariants 的实时输出为准)。未通过真实验收的能力不能宣称完成;搜索相似度不是事实正确概率。审计页检查索引状态与未完成能力。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Project management shared by people and AI agents, with persistent project state through MCP.
Shared control plane for AI coding agents — tasks, memory, decisions, file locks. 12 tools.
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
A project planning board your AI reads and updates over MCP, so the plan stays one plan.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceMulti-project execution, memory, and collaboration platform for humans and AI agents, providing MCP tools for agents to read and write project state.3MIT
- AlicenseAqualityDmaintenanceA local MCP server that enables multiple AI coding tools to share structured project state (decisions, tasks, bugs) so they coordinate without re-explaining.5MIT
- AlicenseAqualityCmaintenanceA shared working-state layer for AI coding tools that provides a persistent notebook for decisions, tasks, and handoffs, enabling seamless context sharing between Claude, Cursor, and other MCP clients.131Apache 2.0
- AlicenseNot gradedqualityBmaintenanceA structured project memory MCP server that persists plans, builds, reviews, and decisions across AI coding sessions and tools, enabling continuous project management with a dashboard.11MIT

