共享项目库

多智能体共用的项目状态控制平面。 不同 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

核心概念

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-services.ps1     # 起 PostgreSQL + memoryd

环境搭建见 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，不需要用户额外提醒。

索引维护先调用 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 各领各的模块，不会抢同一个队列）；不传时先领指派给自己的任务，再领无人认领的，但绝不抢占已指派给别的会话的任务。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 和交接工具；该桥是 worker 入口，不开放创建项目、拆任务、改合同/决策、任务指派、验收对账、架构图导出、投影写入、强制释放工作区等总控或高风险动作。唯一例外是用户明确从该入口新建项目时使用一次 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 会话实例都是独立主体；不能只按模型类型判断权限。同一个模型的不同会话也必须各自领取任务、续租和写自己的检查点。

• 代码地图写入必须绑定当前会话正在执行的任务；整张 replace=true 重写不是普通 worker 操作。

• 合同和决策必须记录创建会话；verified 对账必须由不是任务负责人的独立会话完成。

• DeepSeek 桥默认不开放架构图导出、Obsidian 投影和项目 AGENTS.md 写入；架构图只在用户明确要求时由受控会话生成。

• 终态自动同步会记录代码地图新鲜度：fresh、stale、unversioned 或 missing。地图不新鲜时，交接投影和 Context Pack 会明确警告，不能把它当作当前架构事实。

• 说明书是行为提示，不是安全边界；真正的拒绝在共享服务端执行。

任务合同、工作区、产物、Checkpoint 和对账记录进入共享状态；完整聊天记录、私有推理和未发布文件不会自动进入共享层。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 重建。

交付与验收

详见 docs/PLAN.md 和 docs/STATUS.md。未通过真实验收的能力不能宣称完成；搜索相似度不是事实正确概率。审计页检查索引状态与未完成能力。