AI MemoryHub

AI记忆中枢（AI-MemoryHub）

零依赖、模型无关的 AI Agent 长期记忆系统：Markdown 正文作权威源 + 薄 SQLite 索引，用确定性检索替代向量 RAG，把"理解"交给外层 AI、引擎只做检索与拒答。基于 CEMA（Cognitive Event-driven Memory Architecture，认知-事件驱动记忆架构）概念构建。

个人项目，vibe coding 独立开发：架构与需求设计由本人完成，代码由 AI 辅助实现。

项目介绍

AI记忆中枢（AI-MemoryHub）把"长期记忆"拆成两层：

• 后台正文（权威源）：每个记忆是一个 Markdown 文件，带 YAML front-matter，存全部语义内容。永不参与检索，按需按 ID 取用（即"被遗忘的冷存储"）。
• 前台索引（薄 SQLite 表）：包级表 events 存 package_id / title / summary / tags / linked / filepath / pkage_created / pkage_updated / anchors + 检索四要素 person / event_date / location / topic + search_blob / layer / kind（另有 terms 子实体变体归一表与 anchor_keywords 章级锚点词表），可由所有 .md 的 front-matter 全量重建。检索只发生在这里，命中唯一 ID 后才取正文。

这套设计称为 CEMA（前台薄索引 + 后台正文，前后台严格 1:1、索引可由正文全量重建）——无状态检索、廉价存储不遗忘，且卸下了传统记忆系统的运维重量（无向量基建、无夜间 LLM 流水线、Agent 直写）。

设计为零第三方依赖（仅 Python 标准库），可对接任意 AI 大模型 API，理解层由 AI 客户端 / Agent / 付费 LLM 任一承担。

命名约定：本文档中「AI记忆中枢（AI-MemoryHub）」为本项目正式名称；「HMA」专指其底层架构 Hybrid Memory Architecture（混合记忆架构）。代码中的 hma 包名、MCP server 名、HMA_LLM 环境变量等标识符保持不变。

核心特性

• 事件化记忆：事件为唯一载体，不按短期/长期、情景/语义分类
• 前后台严格分离：薄 SQLite 索引 + Markdown 正文，索引可由 front-matter 全量重建
• 不遗忘、全保留：无重要性评分、无遗忘曲线，判断留给检索时
• 反向量猜测的确定性召回：零向量/零嵌入；F-stage 子实体变体归一 + C+A 章级消歧 + READ 取正文 + 循环查询
• Tag 即 Mod 的包级装卸：复制/删除 memory 下文件夹 = 装卸一块认知
• 模型无关：通用 LLM 适配器，今天 Claude、明天 GPT、后天本地 Ollama 都不用改代码
• 查询契约强制：MCP 边界对每次检索做 QueryEnvelope 校验（缺 keywords/mode 直接挡回）
• 写入安全（门禁）：正式记忆库的写入只认系统内脚本（请求头 + 钥匙表判定）——AI 临时脚本被拦下并报错引导到正确通道；逃生舱需显式理由并留痕
• 全生命周期工具化：新建（五类文本块模板 / 项目模块集）→ 修改（export/import fail-closed）→ 诊断（三层召回诊断），记忆包格式零手搓

本架构的理论主张（为什么这样设计：语义锚点、写入即翻译、确定性作为设计选择、消歧机制、边界与代价）系统化成文于 理论纲领.docx——《过去该如何被拥有？——论大模型智能体的记忆基底》。架构与工程实况（基准口径、规模阶梯实测）见 工程设计.docx；memory/项目/AIMH-design-journal/ 下的设计总纲：写入侧文档（FM 契约 / 收录拆包 / 存储架构）、查询侧文档（检索管线 / 操作手册 / 工具技能 / 领域后处理）、QIR规范（询问代数写法）。本文档只讲「是什么 / 怎么跑」。

项目结构

memory/ 是 AI记忆中枢（AI-MemoryHub）的单一权威存储。每个记忆包 = 一个 .md 事件文件（## 标题树 + YAML front-matter）；全部包共用 memory/index.db 这一单份薄索引（可由所有 .md 的 front-matter 全量重建，删了不丢数据）。

AI-MemoryHub/
├── hma/                          # 引擎核心（零运行时依赖，仅标准库）
│   ├── hma_core.py             # Memory 类：write/query/query_anchors/resolve_query/read_section/link/rebuild/rebuild_all/orchestrate/list_all_in_scope + recall_multihop/query_features
│   ├── core/                   # 引擎内核 10 模块（event_package / fm_yaml / indexing / retrieval* / write_path / kg_builder / aggregate_time …）
│   ├── scoring_coeffs.py       # 打分常量单一调参面（六组系数）
│   ├── envelope.py             # QueryEnvelope 校验层（MCP 边界强制）
│   ├── cli.py                  # 命令行入口
│   ├── server.py               # MCP server（stdio JSON-RPC，12 工具）
│   ├── engine/                 # 分支接口 / CLI（dispatch + @register + handlers）
│   ├── paths.py                # 仓库根 / memory 目录唯一真相源
│   ├── recall_obscure.py / refine.py / routing.py
│   ├── ingest.py               # AI 收录管线（run_ingest）
│   ├── daylog.py / llm_adapter.py
├── scripts/                      # 按用途分层的独立确定性脚本（零依赖、可单独跑）
│   ├── ingest/                 # 收录写入（new_package / daylog_append / compact / archive_paper / pdf_reflow / memory_append_section）
│   ├── maintain/               # 维护门禁（rebuild_index / relocate_package / doctor / lint_memory / preflight / derive_topic_views / scan_docx）
│   ├── infra/                  # 部署运行时（deploy_mcp / mcp_launch / where / sync_skills / periodic_review）
│   ├── query/                  # 查询解析（oc_registry / parse_time_iso）
│   ├── diag/                   # 诊断取证（audit_comment_pins / audit_orphans / clarify_log / clarify_metrics / peek_index / scan_fm）
│   └── hooks/                  # 客户端注入（aimh_recall_card_hook）
├── skills/                      # 技能（项目级副本，与用户级双副本；含召回失败三层诊断 aimh-recall-diagnose）
├── memory/                      # 权威记忆库（单一真相 + index.db 薄索引）
├── 网页控制台/                   # 零依赖单文件前端（只读浏览记忆库）
├── 一键更新记忆索引.exe          # 一键重建索引（rebuild_index.py 的 PyInstaller 打包，双击即用零 AI；引擎大改后需重新打包）
├── pyproject.toml               # 零运行时依赖声明
└── README.md

执行流程

安装

pip install -e .          # 提供 hma-mcp / hma 两个命令

pyproject.toml 声明零运行时依赖（仅标准库）。无需任何向量库或外部服务。

三种用法

1. 命令行（人工 / 脚本）

python -m hma.cli --root memory write \
  --id proj-rag --title "放弃 RAG 主记忆" --summary "改事件驱动分层" \
  --tags project,decision --aliases "分层记忆" --body "# ...\n正文"

python -m hma.cli --root memory query "分层记忆" --top-k 5
python -m hma.cli --root memory link proj-rag todo-mcp
python -m hma.cli --root memory show  proj-rag
python -m hma.cli --root memory list
python -m hma.engine rebuild-all --root memory   # 全量重建索引；删了 index.db 也能恢复

2. MCP server（接任意 AI 客户端）⭐ 推荐

python -m hma.server --root memory
# 或 entry point： hma-mcp --root memory

stdio 上的 JSON-RPC 2.0，暴露 12 个工具（对应三级检索漏斗 L1→L2→L3 + 写入/关联/重建/收录 + 聚合/时间/细节追问/词表）：

Claude Desktop / Codex / Cline / WorkBuddy 等任何 MCP 客户端，加一段配置即可：

{
  "mcpServers": {
      "aimh": {
        "command": "python",
        "args": ["-m", "hma.server", "--root", "/path/to/AI-MemoryHub/memory"]
      }
  }
}

WorkBuddy 即插即用部署：仓库自带一键部署脚本，把启动器复制到 WorkBuddy 配置目录、合并写出 ~/.workbuddy/mcp.json（只动 aimh 连接器、保留其它、自动探测 python 版本、不写死路径），并登记 ~/.hma_home 指针：

python scripts/infra/deploy_mcp.py            # 部署（幂等，可重跑）
python scripts/infra/deploy_mcp.py --dry-run  # 只预览将写出的配置

部署后在 WorkBuddy 连接器管理页点「信任」激活 aimh 连接器，新窗口即出现 mcp__aimh__* 工具。

⚠️ 改 server.py 后需在连接器里禁用→启用 / 重新 Trust，长驻进程才加载新代码。

3. 作为库（Python import）

from hma.hma_core import Memory
m = Memory("memory")
m.write(id="x", title="X", summary="s", tags=["t"], body="# X\n正文")
for rid, title, summary, score in m.query("x"):
    print(rid, score)

写入与收录

主动收录（memory_ingest）——用户贴文本，AI 执行完整管线：读取现有包摘要做关联发现 → 按 CEMA 凝聚性+体积闸门拆分为事件包 → 为每个包生成元数据 → 写入 .md 权威源 + upsert 索引 → 与现有/新建包建立双向关联。未配置 LLM API 时退化为单包启发式，工具永远可用。

# 有 LLM：AI 自动拆分+关联
echo "周会：放弃 RAG，改事件驱动；下周三前完成 MCP 评审。" \
    | python -m hma.cli --root memory ingest --scope 其他

# 无 LLM / 不想调模型：单包兜底
echo "随手记一条想法" | python -m hma.cli --root memory ingest --no-llm

零成本路径（Agent 即理解层）：未配置 key 时，让当前会话 Agent 充当理解层（加载 aimh-ingest 技能），由确定性引擎落库——与付费 LLM 路径同构可替换。当文本类型不确定时，先加载 aimh-intake 元路由技能做分类决策，再链式加载 oc-dossier / aimh-ingest 对应技能落库，自己不写任何 memory/ 文件。

确定性落库 / 改包（scripts/ingest/new_package.py，推荐入口）——记忆包全生命周期格式零手搓：

# 新建：出类型 dict 模板（通用/对话记录/论文orig/论文review/疾病），AI 填好 JSON 后 fail-closed 落盘
python scripts/ingest/new_package.py --print-dict --type 疾病
python scripts/ingest/new_package.py --type 疾病 --path "memory/其他/医疗" --id 心包炎 \
    --fill fm.json --body-file body.md

# 新建整项目：一键建齐 4 状态模块骨架（需求清单/项目结构/约定/架构，互链）
python scripts/ingest/new_package.py --module-set 项目 --path "memory/项目/新项目" --project 新项目

# 修改既有包：拆出 fm.json + body.md 编辑后 fail-closed 写回（pkage_updated 自动更新）
python scripts/ingest/new_package.py --export "memory/<路径>/<包>.md"
python scripts/ingest/new_package.py --import "memory/<路径>/<包>.md" --fill fm.json --body-file body.md

校验渲染复用 fm_schema 权威实现（校验不过不落盘）；默认拒绝覆盖、路径软检查（单存储 + R59 中文命名）。落盘成功后收尾自动重建索引（红线「落 .md 必重建」机制化；--no-rebuild 可跳过——批量多次写入时建议用它、收尾跑一次 rebuild_index.py）。

付费/本地路径：设 HMA_LLM（并配好对应 key/端点）即自动改走 llm_adapter 真实 LLM，无需改任何代码；LLM 调用失败会自动退回启发式。

时间轴：单日记录包（daylog）

主记忆库按主题而非时间线组织；daylog 补上正交的时间轴，不破坏主题原则。

写入走 scripts/ingest/daylog_append.py（hma.engine 无 daylog 子命令），必填 --title + --anchor-about + --anchor-keywords，新建当天日文件时另需 --summary；四项缺任一即 fail-closed 拒绝落盘：

python scripts/ingest/daylog_append.py \
    --title "一句标题" --body "一段叙事：这天发生的事" \
    --anchor-about "本条锚点的特征化摘要（AI 阅读正文后语义填写）" \
    --anchor-keywords "关键词1,关键词2" \
    --linked 主题包id --tags 关键词1,关键词2 [--date 2026-07-25]

--anchor-about / --anchor-keywords 必须由 AI 语义填写，脚本不做机械兜底、也不从 --tags 搬运；--body 缺省读 --body-file 或 stdin。--date 缺省今天。

读取无 CLI 子命令，走 hma.daylog 的 Python API：

from hma.daylog import read_day, days_in_range
read_day("memory", "2026-07-25")              # 全天
days_in_range("memory", "2026-07-01", "2026-07-25")   # 区间

时间是过滤键不是权重（定位 = id 内嵌日期的确定性比较，不做新鲜度加权）。模糊时间语（"前天/上周三"）由 Agent 解析成 ISO 日期后再调命令。

上下文压缩归档（昼夜节律 · Agent 即理解层）

当上下文窗口将满时，把已讨论完、暂未落库、但以后可能要用的溢出内容，由 Agent 判定落点 + 生成冷凝摘要，确定性写交 scripts/ingest/compact.py：

python scripts/ingest/compact.py \
    --root memory --sink <日志|cache|progress> \
    --summary "<冷凝摘要>" --source "<溢出来源>" \
    [--date YYYY-MM-DD] [--id <eid> --title "<标题>"] [--project <pid>] \
    [--linked a,b] [--tags x,y] [--conflict-event <id> --conflict-intro "<一句话>"]

--sink 三个落点：日志（叙事/时间线，追加进 memory/日志/daylog-YYYY-MM-DD.md，可用 --date 指定归属日）、cache（纯溢出缓存，需 --id + --title）、progress（项目进度，需 --project + --id + --title）。传 --conflict-event 进入冲突覆盖模式时 --sink 可省略。

铁律：压缩 = 加法式冷摘要，权威原文一字不动；仅当新信息与某权威事件真正冲突时才覆盖并追加可审计 trail。

进阶检索（scope / 拒答 / 多问 / 枚举）

写时与读时的几档增强机制，详见 查询侧文档.md【手册】篇：

• 聚焦 scope：传入目录路径只召回该子树，屏蔽跨子树干扰（29 包 → 11 包），只收束范围不替拒答。
• 拒答层 allow_abstain：覆盖不足/域外查询显式返回拒答，避免编造（V1.0 已落地，默认开）。
• 多问 sub_queries：AI 一次给子问清单，引擎确定性扇出合并，不单独往返。
• 枚举 enumerate：列出 scope 子树内全部包（非 Top-K 排序）。
• 多跳 multihop：沿写入时策展的 linked 边 BFS 扩簇，补关系/结构盲区（opt-in）。

所有检索类 MCP 调用都受 QueryEnvelope 契约约束（MCP 入参 q/keywords/mode 必填——引擎信封字段名为 query）。护栏/契约拒绝的回包口径（【M11-MCP·治本】）：isError: true + 结构化负载 {"ok": false, "code": "...", "msg": "..."}，code 取值以 hma/server.py 的 MCP_ERROR_CODES 注册表为唯一真相源（WRITE_GUARD / ENVELOPE_VIOLATION / AGG_GUARD / TIME_FILTER_GUARD / OBSCURE_GUARD / BAD_UNIT / ERROR）；ABSTAIN（拒答）是合法语义结果，照常 isError: false 返回、不属错误。

当前状态

项目状态（2026-10-14）：开发周期收官，进入使用/运维态。同日收尾落产两件运维安全件：写入门禁（对临时脚本写 memory 的拦截 + 报错引导正确通道）与全链路自动重建（写 .md 后自动重建索引；-S 启动优化 / 增量 / 幂等等已齐备）。检索主线（打分框架、dK 裁切、拒答层、澄清反问、细节追问锁章、QIR 询问代数）已全部落产。库内一键自检：python scripts/maintain/preflight.py（六步：编译门禁 + import 冒烟 + front-matter lint + doctor 体检 + 静默吞锁量 + docx 陈旧词扫描——except: pass 存量按文件锁定、新增即红；全程只读）；全量回归在父级脚手架 AIMH-devkit/：runner 为 AIMH-devkit/run_all_regress.py（在项目外根目录，不在 tests/ 下），一键复跑；默认执行 tests/ 下 33 个 .py（其中 regress_*.py 27 个文件，_ 开头的 12 个是辅助件、runner 跳过）。runner 按脚本计项（三态 SYNTAX / FAIL / OK，一个脚本一项），不按用例切分——故无「用例总数」这一口径；测试不入库是有意决策。网页控制台、医学/法律领域适配、记忆包全生命周期工具（new_package.py）与召回失败三层诊断（aimh-recall-diagnose）齐备。接下来以日常使用驱动维护：内容蒸馏回填、按需修病灶。挂起事项（LoCoMo 全量跑分）在有可用 LLM 资源时可随时恢复。

定位：零依赖参考实现 + 个人哲学试验场——把事件化记忆、前后台分离、不遗忘、反向量猜测等设计在零依赖下做了工程验证，并接入召回检索四要素、F+C+A+READ 三段式锚点管线、LoCoMo / MemoryStress 基准评测。

已兑现的哲学：事件化记忆 · 前后台严格分离 · 不遗忘全保留 · 反向量确定性召回 · Tag 即 Mod 包级装卸 · 跨窗口离线整合（昼夜节律）。

工程状态：

• 零第三方运行时依赖（仅 Python 标准库）
• MCP server 暴露 12 工具（write / query / query_anchors / resolve / read_section / vocab / link / rebuild / ingest / aggregate / time_filter / obscure_recall）
• 打分常量单一调参面 hma/scoring_coeffs.py（六组系数）；dK 关联度分差裁切（锚点级瀑布式）落产
• 澄清反问（clarify，Venn 独有弧段）+ 细节追问三态锁章（obscure_recall / context-scope）落产，与拒答层共同构成对向量 RAG 的护城河
• 召回机械层收编 hma/recall_obscure.py（章级切分 / 局部倒排 / 重叠合并 / 瀑布裁切，零依赖）
• 网页控制台（网页控制台/）：零依赖单文件前端 + vendored marked.js，只读浏览记忆库
• 医学 / 法律领域适配规范落库（一病一包与分阶段筛查、法条引证变体归一）
• 记忆包全生命周期确定性工具 scripts/ingest/new_package.py：五类文本块模板新建、项目 4 模块集骨架、--export/--import fail-closed 改包（旧式 FM 自动归一）
• 召回失败三层诊断技能 aimh-recall-diagnose（FM 字段 → index.db → 代码流程，案例皆真实病灶）
• 仓库带 git 基线与版本控制（契约文档 / 引擎核心全部入库；CHANGELOG.md 与 daylog 本体留本地不跟踪）
• 召回检索四要素（person / event_date / location / topic）已为一等字段，读取期软加权
• 锚点级检索已升级为 F+C+A+READ 三段式（生产引擎已闭环）
• 拒答层 V1.0 已落地（四道闸 + corpus_missing_entity 硬拒，allow_abstain 默认开）
• QueryEnvelope 契约已落地（MCP 边界强制 q/keywords/mode，多问扇出 sub_queries、枚举 list_all_in_scope）
• MCP 失败语义协议化：护栏/契约拒绝一律 isError: true + 结构化 {"ok": false, "code", "msg"}，错误码以 MCP_ERROR_CODES 注册表为唯一真相源（拒答 ABSTAIN 属合法结果，不走错误通道）
• 脚本按用途六层：scripts/{ingest, maintain, infra, query, diag, hooks}——收录写入 / 维护门禁 / 部署运行时 / 查询解析 / 诊断取证 / 客户端注入 分目录，调用方式不变
• 静默吞锁量门禁：全仓 except: pass 存量按文件锁定（基线 JSON），新增即 preflight 红——防"静默失败"回潮
• 技能作为即插即用客户端 + 常驻主动触发技能（aimh-always）
• 技能挂载到客户端发现位（如 junction ~/.zcode/skills → 项目 skills/）后穿透生效，但 Skill 可用列表在会话启动时固定——挂载后需新开会话才出现在技能菜单；当轮可读 SKILL.md 照规程等效执行

基准评测（已跑通真实数据闭环）：

• LoCoMo 1540 题：hit@30 ≈ 99.6% / recall@30 ≈ 99.5% / hit@5 89.7–92%
• MemoryStress 300 题：baseline 77% / B_gold 89.7%

完整口径（含红线：OMEGA 38.3% 不可并列、TrueMemory 93% 作对齐目标）见 工程设计.docx 工程实况章。

已知缺口：

• 窗口内实时活文档整合重置（边对话边把碎片整合进既有正文）在当前 Transformer 架构下做不出完整版，留待非 TF 架构（持久状态 SSM/Mamba 类，或真 AGI）
• 网页控制台的知识图谱页展示的是已退役机制的冻结数据（2026-10-11 退役，快照不再更新）
• 引擎 API 直接调用绕过 MCP 边界的 QueryEnvelope 约束（预期隔离，测试脚本走 API 不受影响）
• 架构权衡（能力上限在 AI 层）：CEMA 把理解力（归约/判 mode/抽 keywords/拆 sub_queries/策展 linked）集中押在 AI 层，引擎只做确定性执行。收益是引擎极小、可调试、随 AI 升级白赚；代价是 AIMH 的质量上限 = 配对 AI 的智能上限——AI 弱则退化为「偶尔用错的漂亮文件柜」。三道缓冲（信封硬校验/写时策展摊销/拒答闸兜底）把「AI 可能笨」变为「可控且可纠正」，但不消除该上限。理论论证详见 理论纲领.docx「边界与代价」。

License

MIT