AI记忆中枢(AI-MemoryHub)
零依赖、模型无关的 AI Agent 长期记忆系统:Markdown 正文作权威源 + 薄 SQLite 索引,用确定性检索替代向量 RAG,把"理解"交给外层 AI、引擎只做检索与拒答。基于 CEMA(Cognitive Event-driven Memory Architecture,认知-事件驱动记忆架构)概念构建。
个人项目,vibe coding 独立开发:架构与需求设计由本人完成,代码由 AI 辅助实现。
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
零依赖、模型无关的 AI Agent 长期记忆系统:Markdown 正文作权威源 + 薄 SQLite 索引,用确定性检索替代向量 RAG,把"理解"交给外层 AI、引擎只做检索与拒答。基于 CEMA(Cognitive Event-driven Memory Architecture,认知-事件驱动记忆架构)概念构建。
个人项目,vibe coding 独立开发:架构与需求设计由本人完成,代码由 AI 辅助实现。
零依赖确定性 Agent 长期记忆系统 — Markdown 权威源 + 薄索引,拒答/澄清替代向量硬猜,玻璃盒可审计。 | Zero-dependency deterministic agent memory system — Markdown authoritative store + thin index, refuse/clarify instead of vector guessing. A glass-box alternative to RAG.
AI记忆中枢(AI-MemoryHub)把"长期记忆"拆成两层:
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环境变量等标识符保持不变。
keywords/mode 直接挡回)本架构的理论主张(为什么这样设计:语义锚点、写入即翻译、确定性作为设计选择、消歧机制、边界与代价)系统化成文于
理论纲领.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 声明零运行时依赖(仅标准库)。无需任何向量库或外部服务。
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 也能恢复
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,长驻进程才加载新代码。
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 补上正交的时间轴,不破坏主题原则。
写入走 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 判定落点 + 生成冷凝摘要,确定性写交 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。
写时与读时的几档增强机制,详见 查询侧文档.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 包级装卸 · 跨窗口离线整合(昼夜节律)。
工程状态:
hma/scoring_coeffs.py(六组系数);dK 关联度分差裁切(锚点级瀑布式)落产hma/recall_obscure.py(章级切分 / 局部倒排 / 重叠合并 / 瀑布裁切,零依赖)网页控制台/):零依赖单文件前端 + vendored marked.js,只读浏览记忆库scripts/ingest/new_package.py:五类文本块模板新建、项目 4 模块集骨架、--export/--import fail-closed 改包(旧式 FM 自动归一)aimh-recall-diagnose(FM 字段 → index.db → 代码流程,案例皆真实病灶)CHANGELOG.md 与 daylog 本体留本地不跟踪)corpus_missing_entity 硬拒,allow_abstain 默认开)q/keywords/mode,多问扇出 sub_queries、枚举 list_all_in_scope)isError: true + 结构化 {"ok": false, "code", "msg"},错误码以 MCP_ERROR_CODES 注册表为唯一真相源(拒答 ABSTAIN 属合法结果,不走错误通道)scripts/{ingest, maintain, infra, query, diag, hooks}——收录写入 / 维护门禁 / 部署运行时 / 查询解析 / 诊断取证 / 客户端注入 分目录,调用方式不变except: pass 存量按文件锁定(基线 JSON),新增即 preflight 红——防"静默失败"回潮~/.zcode/skills → 项目 skills/)后穿透生效,但 Skill 可用列表在会话启动时固定——挂载后需新开会话才出现在技能菜单;当轮可读 SKILL.md 照规程等效执行基准评测(已跑通真实数据闭环):
baseline 77% / B_gold 89.7%完整口径(含红线:OMEGA 38.3% 不可并列、TrueMemory 93% 作对齐目标)见
工程设计.docx工程实况章。
已知缺口:
理论纲领.docx「边界与代价」。MIT
零依赖确定性 Agent 长期记忆系统 — Markdown 权威源 + 薄索引,拒答/澄清替代向量硬猜,玻璃盒可审计。 | Zero-dependency deterministic agent memory system — Markdown authoritative store + thin index, refuse/clarify instead of vector guessing.
總覽
零依赖确定性 Agent 长期记忆系统 — Markdown 权威源 + 薄索引,拒答/澄清替代向量硬猜,玻璃盒可审计。 | Zero-dependency deterministic agent memory system — Markdown authoritative store + thin index, refuse/clarify instead of vector guessing. A glass-box alternative to RAG.
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
AI MemoryHub 透過 stdio 在本機執行。
上次檢查時間:2026-10-28。 零依赖确定性 Agent 长期记忆系统 — Markdown 权威源 + 薄索引,拒答/澄清替代向量硬猜,玻璃盒可审计。 | Zero-dependency deterministic agent memory system — Markdown authoritative store + thin index, refuse/clarify instead of vector guessing. A glass-box alternative to RAG.