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_*.py27 个文件，_开头的 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/--importfail-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 题：
baseline77% /B_gold89.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
