盘古记忆 Mlte0907/pangu

盘古（Pangu）— 给 AI 助手装上长期记忆

v0.4.1 · 会遗忘、会联想、会巩固 · MCP + REST + Web UI

盘古是一个本地优先的 AI 记忆服务：把你说过的话、写过的笔记、丢进来的文档，变成 AI 随时能查的长期记忆 —— 而且像人一样遗忘（不重要的自然淡出）、联想（相关的被一起唤醒）、巩固（碎片随时间整理成知识）。

任何支持 MCP 的客户端（DeepSeek Harness / Claude Code / 自研 Agent）接上它就能记住你。
不用 DSH 也完全能用。

三步跑起来

① 一条命令安装（Linux / macOS · Python ≥ 3.11 · 约 10 分钟）

curl -fsSL https://raw.githubusercontent.com/Mlte0907/pangu/master/install.sh | bash

装完会打印一张 「DSH 填写卡」（服务地址 + 凭据），只显示一次，先存下来。

②（可选）接上你的 AI 客户端

| 客户端 | 怎么做 |
| DeepSeek Harness | 装可选插件 dsh-pangu，一条命令（见下方「接入 DeepSeek Harness」） |
| Claude Code / 其它 MCP 客户端 | 见下方「手动安装」里的三种接入方式 |
| 只想先看看界面 | cd ~/pangu && .venv/bin/pangu serve → 浏览器打开 http://127.0.0.1:8866 |

③ 开始用

cd ~/pangu # 默认安装目录
.venv/bin/pangu stats # 装好没、有多少条记忆 .venv/bin/pangu search "关键词" # 搜一条 .venv/bin/pangu --help # 30+ 子命令

安装失败 / 网络问题 / 想要更多细节 → 看下方「安装（详细）」。

核心能力

| 能力 | 说明 |
| 🧠 记忆宫殿 | Wing→Room→Drawer 三级组织，7 种语义殿堂分类（事实/事件/发现/偏好/建议/概念/关系），跨翼 Tunnel 联通 |
| ✍️ 摄入管道 | 标准脱敏 → 可选 Fernet 加密 → 三级去重（精确 / 语义余弦 0.92 / 文本重叠）→ 重复记忆自动 boost |
| 🔍 混合检索 | ONNX 本地向量（paraphrase-multilingual-MiniLM-L12-v2 INT8，384 维，中英都行）+ SQLite FTS5（jieba 中文分词）+ RRF 倒数排名融合（k=60）+ 多维重排 |
| 🌊 神经激活扩散 | top-K 命中做 spreading activation（深度 3、衰减 0.6），把关联记忆一并唤醒 |
| ⏳ 个性化遗忘 | 艾宾浩斯式衰减曲线按记忆类型（情景 0.6 / 语义 0.15 / 程序 0.08 / 情绪 0.3）区分速率；凌晨 3-5 点夜间巩固因子；低于底限自动归档 |
| 📚 四层记忆栈 | L0 身份层 → L1 概要层 → L2 按需层 → L3 深度搜索，动态 token 预算（1000→3000）随记忆规模伸缩 |
| 🔐 安全 | Fernet 记忆级加密、MemorySanitizer 标准脱敏、JWT / API-Key / RBAC / ABAC 四层鉴权 |
| 🕸️ 知识结晶 | LLM 生成 WikiPage 知识页、Wikilink 实体抽取、知识图谱可视化 |
| 🔄 自动沉淀 | MCP 工具调用透明采集（SelfImproveWorker）、会话桥接摘要、git hook、文件监控 |
| 🖥️ 三形态接入 | MCP stdio / MCP streamable-HTTP + REST/WebSocket / 独立 Web 服务 |
| 🧩 多模态（默认关闭） | PDF 正文（pypdf）、音频转写（whisper，需另开语音转写）、图片尺寸（Pillow，无 OCR）—— 在设置页「多模态内容提取」一键打开 |

安装（详细）

一键安装（推荐）

git clone https://github.com/Mlte0907/pangu.git
cd pangu
./install.sh # 装依赖 + 预下载模型 + 注册 systemd 服务 ./install.sh --dsh-plugin # 盘古与 DSH 同机时追加

安装结束会打印 DSH 插件填写卡（服务地址 / 盘古凭据，只显示一次）。
填进 DSH 设置页 →「盘古记忆系统」即可——设置页只有一个凭据字段「盘古凭据」，记忆与管理面板都用它（安装脚本已让服务端两个密钥同值）。

云端部署

盘古装在云主机、DSH 装在你自己的机器上时，在云主机上执行：

git clone https://github.com/Mlte0907/pangu.git /root/pangu && cd /root/pangu
./install.sh --host 0.0.0.0

脚本结束会打印 DSH 插件填写卡（服务地址 / 盘古凭据），只显示一次，请立即保存。

💡 设置页只有一个凭据字段：安装脚本让 ~/.pangu/.api_key 与 ~/.pangu/.admin_secret 取同一个值，插件在管理面直接复用「盘古凭据」，所以只需填一处。
（服务端仍是两套独立校验——数据面走 X-API-Key、管理面走 X-Admin-Key；共用只是安装期的取值策略。若某台服务端两把确实不同，插件管理面会 401，安装脚本的填写卡会直接给出「在服务端统一」的那一行命令。）

⚠ --host 0.0.0.0 会把端口暴露到公网，必须置于 nginx/TLS 反向代理之后（参考 DEPLOY.md），并在防火墙/安全组只放行反向代理端口。

备选：脚本单文件"一条命令"

sh
curl -fsSL https://raw.githubusercontent.com/Mlte0907/pangu/master/install.sh | bash -s -- --host 0.0.0.0

⚠ 网络前提：这条命令要先下载 install.sh 本身，依赖 raw.githubusercontent.com。
中国大陆该域名常被重置（现象：curl: (56) Recv failure 或长时间无响应无输出），
此时请改用上面的 git clone 方式 —— 实测 git clone https://github.com/... 在国内可直连。若确实只想要单文件脚本，可走第三方 GitHub 加速镜像：

sh
curl -fsSL https://ghproxy.net/https://raw.githubusercontent.com/Mlte0907/pangu/master/install.sh | bash -s -- --host 0.0.0.0

镜像属第三方服务，可用性与内容完整性不由本项目保证；有顾虑请用 git clone。

脚本会做完整的环境自检，并在 ONNX 模型下载失败时明确报错中止（而不是让服务静默降级到无语义的 hash 向量，见 docs/OPTIMIZATION.md）：

./install.sh --help # 全部选项 ./install.sh --no-service # 只装到目录，不注册服务 ./install.sh --port 19529 # 自定义端口 ./install.sh --offline-model m.onnx,tokenizer.json # 内网/弱网：从本地文件装模型

手动安装 sh 安装（Python ≥ 3.11）
pip install -e .

依赖说明

核心依赖不含 torch / sentence-transformers / chromadb / openai-whisper。
这些包会传递引入约 1.3GB 的 CUDA 轮子（nvidia-cudnn 620MB、nvidia-cublas 517MB、triton 216MB 等），而它们的代码路径全部是惰性导入，在无 GPU 的机器上永不执行：

| 包 | 引用位置 | 是否影响启动 |
| sentence-transformers | pangu/search/embedder.py:74（@property model 内） | 否，默认走 ONNX |
| torch | pangu/memory/image_engine.py:85,111,139（CLIP 图像向量） | 否，try/except 降级 |
| openai-whisper | pangu/memory/audio_engine.py:34（@property whisper 内） | 否，失败降级 |
| chromadb | 全库无 import，仅 config.backend 默认值 | 否 |

默认嵌入路径是 ONNX（onnx_enabled 默认为 True，见 pangu/core/config.py:135），无需 torch。实测在 aarch64 无 GPU 环境下：核心依赖 56 包 / 223MB；安装耗时因缓存状态而异——

| 场景 | 耗时 |
| uv 全局缓存已存在 | 约 20 秒 |
| 首次安装（冷缓存） | 约 8 分 10 秒 |
| 加上 ONNX 模型下载（源可达） | +约 30 秒 |

首次安装请预留 10 分钟以上；onnxruntime(54MB) 与 numpy(55MB) 是大头，中途别中断（中断会导致缓存已下载但包未装好）。
而包含 torch 的完整集会下载 987MB 以上仍难以落盘。

需要图像 / 音频 / 备用嵌入能力时（装完依赖还要在 DSH 设置页打开开关才生效：「多模态内容提取」管 PDF/音频/图片抽取、「语音转写」管音频转写 —— 两者都默认关闭）：

sh
无 GPU 机器建议先装 CPU-only 轮子，可省下全部 CUDA 负载
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install -e ".[multimodal]"

⚠ 注意两个不同的服务——最容易搞混的地方：

| 端口 | 应用 | 启动方式 | 用途 |
| 19529 | pangu/api/server.py | pangu serve --api / ./install.sh / ./start.sh | MCP + REST，DSH 插件连这个 |
| 8866 | pangu/server/web_server.py | pangu serve | 浏览器仪表盘，不含 MCP 接口 |

pangu serve（不带 --api）启动的是 8866 的界面服务，不能替代 19529。
sh
方式一：MCP over HTTP（API + MCP 同端口，生产推荐） pangu serve --api --host 127.0.0.1 --port 19529

方式二：MCP stdio（Claude Code / 其它 MCP 客户端） pangu mcp

方式三：独立 Web 服务（不含 MCP） pangu serve # http://127.0.0.1:8866

pangu serve --api 若未指定 --port，会自动用 19529（而不是 8866），避免与 Web UI 端口冲突。

Docker
sh
docker compose up -d

接入 DeepSeek Harness（可选插件）不装也能用 —— 盘古本体是独立服务（MCP / REST / Web UI 三种接入都有）。
只有当你想在 DSH 会话里直接读写记忆、并想有个面板看记忆状态时，才需要它。

插件已独立成仓：Mlte0907/dsh-pangu。
装上后它让 DSH 会话自动拥有盘古记忆：

- 记忆注入：system-prompt/assemble waterfall 每轮取会话意图检索相关记忆（top-5，每条 200 字符），以 [盘古记忆系统] 上下文块注入——异常时静默降级，永不阻塞会话；
- 工具暴露：服务端默认收敛为 28 个核心工具的白名单（见下方说明），经宿主 MCP 客户端直连（streamable-http，60s 超时）。
关于“白名单”的两层含义 —— 容易混淆，这里说清楚：

1. 服务端白名单（真实生效）：盘古自身有三级工具暴露机制（core / optional / experimental，见 pangu/server/exposure.py 与 pangu/core/config.py:39）。缺省即收敛为 28 个核心工具，其余 100+ 个工具不会出现在 /mcp 的 tools/list 中。若要放开，在 ~/.pangu/config.json 配置： json { "exposure": {
"enabled_optional_modules": ["multimodal", "knowledge_graph"],
"enabled_core_modules": ["search", "palace"],
"enabled_experiments": ["causal", "advanced"] } }
可选模块：multimodal / timeline / analytics / quality / consolidation / embed / knowledge_graph / wiki / llm_tools / session。
- enabled_core_modules 用来展开 core 层的非白名单工具（pangu_fts_search / pangu_holographic_encode 等约 76 个）。
core 层默认启用，但这些工具此前没有任何配置途径可以暴露。
- enabled_experiments 按实验组名启用，advanced 是 experimental 层的容器模块（其工具名不带实验前缀）。
- 实测规模：默认 28 → 全开 408 个工具。

错误码：1001 = 工具不存在；1002 = 工具存在但所在模块未启用（按提示在 exposure 段开启即可）；5000 = handler 抛出异常。

2. 客户端白名单（不生效，已移除）：本插件早期在 cordis.patch.yml 中配置过 tools.allow，但 @deepseek-ai/dsh-mcp-client 的 Config schema 不含 tools 键，该键会被 schemastery 非严格模式静默忽略且无告警——工具照样全部注册。因此该配置已删除，以免造成 “看似有保护、实际没有”的错误预期。要限制工具范围，请用上面第 1 种。
- 仪表盘：侧栏指标卡 + “盘古”标签页（概览 / 3D 星系记忆图谱 / 知识卡片）+ 设置页配置读写。
- 设置页填写 LLM：DSH 设置 →「盘古记忆系统」，可直接选择提供商（OpenAI / DeepSeek / 智谱 / 通义 / OpenRouter / Ollama）、填模型名、Base URL 与 API Key，并可用「测试连接」验证该组合是否真的可用。API Key 不回显明文（只显示 **后4位），保存后写入 ~/.pangu/.llm_api_key（权限 0600），不进 config.json，重启不丢。

因为明文不下发到页面，密钥输入框留空 = 保持原有 Key 不变；只改模型或 Base URL 时不必重填 Key。想清除 Key 需显式清空 ~/.pangu/.llm_api_key。

未配置 LLM 时记忆的存入与检索完全正常（走 ONNX 本地嵌入），仅「知识结晶 / 记忆蒸馏 / 摘要」等需要语言模型的功能会被跳过。

安装插件（一条命令，脚本会自举拉取插件仓 → 装依赖 → 接进 DSH profile）： sh
curl -fsSL https://raw.githubusercontent.com/Mlte0907/dsh-pangu/main/install.sh | bash
./install.sh tui # 换 profile：先 clone 插件仓再 ./install.sh

盘古与 DSH 同机时也可以让盘古的安装脚本顺带拉取安装： sh
cd ~/pangu && ./install.sh --dsh-plugin # 拉取到 ~/.dsh-pangu 并安装

装完重启 DSH，然后 设置 →「盘古记忆系统」填两个字段：盘古服务地址 + 盘古凭据（都在盘古安装脚本打印的「DSH 填写卡」里）。

注：cordis.patch.yml 的 HMR 在 web 实例不生效，改后需重启 DSH。
yaml
cordis.patch.yml（关键片段）
- insert:
- id: mcp-pangu
name: '@deepseek-ai/dsh-mcp-client'
config:
transport: streamable-http
url: http://127.0.0.1:19529/mcp
- id: pangu-dashboard
name: dsh-pangu

记忆是怎么工作的检索 → 注入用户发消息 → 插件 waterfall 取会话意图 → MCP pangu_search_memories(limit=5) → HybridSearch：语义向量（0.65 阈值）+ FTS5 中文全文 → RRF 融合 + 衰减分/重要性/标签重排 + 神经激活扩散
→ [盘古记忆系统] 上下文块注入 system prompt

写入 → 落盘 Agent 调 pangu_add_memory（或 REST remember()） → 脱敏 → 加密(可选) → 三级去重 → 融合 → embedding → 索引 → 冲突检测 → 原子写 ~/.pangu/pangu.db/v2_memories/drawers.json

后台 → 巩固每 30 分钟：遗忘曲线衰减 + 夜间巩固因子 + 低于底限归档透明采集：工具调用自动沉淀为 self_improvement 翼记忆

完整内部原理（含全部文件:行号证据链）见 docs/memory-system-internals.md。

配置

配置文件 ~/.pangu/config.json，全部字段可用 PANGU_ 环境变量覆盖：

| 配置 | 默认 | 说明 |
| port | 19528 | API 端口（install.sh 部署的服务用 19529） |
| onnx_enabled | true | 本地 ONNX 嵌入（离线可用，模型自动下载） |
| embed_api_url | 空 | 外部 embedding API（设置后优先于 ONNX） |
| allow_hash_fallback | false | 是否允许降级为 hash 向量（详见下方"检索结果不对劲"） |
| similarity_threshold | 0.65 | 向量检索相似度阈值 |
| decay_base / decay_floor | 0.95 / 0.15 | 遗忘曲线基数 / 归档底限 |
| neural_enabled | true | 海马体神经激活扩散 |
| api_key / jwt_secret | 空 | 为空则不启用鉴权（生产建议开启） |

敏感字段（api_key / jwt_secret 等）在对应 PANGU_ 环境变量存在时会从 JSON 中忽略并告警。

嵌入缓存（跨进程持久化）

嵌入是整个检索链里最贵的一步（约 12–14 ms/条），所以算过的向量会被缓存。
缓存落盘在 ~/.cache/pangu/embedding_cache.json，重启后依然有效：

| 场景 | 重启后首次搜索耗时 |
| 持久缓存生效（默认） | 7.4 ms |
| 关闭持久化 | 696.9 ms |

（真实 41 条抽屉实测；记忆量越大差距越大。）

| 环境变量 | 默认 | 说明 |
| PANGU_CACHE_DIR | ~/.cache/pangu | 缓存目录，可改到别处 |
| PANGU_EMBEDDING_CACHE | 1 | 设 0 关闭持久化（退回纯内存） |

缓存自带指纹校验：换了嵌入模型或维度，旧缓存会自动整体作废，不会把不同模型的向量混在一起用。缓存文件损坏也只是当作"未命中"，不会影响服务启动。

检索结果不对劲？（嵌入降级自查）

盘古的嵌入是三级降级：远程 API → ONNX → hash 向量。

⚠ 最后一级的 hash 向量是字符 trigram 哈希，它合法、非零、维度正确，但没有任何语义能力——相同含义的文本彼此不相近。此时服务照常启动、检索照常返回结果，只是结果没有意义（实测 cos(猫,dog)=0.0000）。

自查一行命令： sh
curl -s http://127.0.0.1:19529/health

| 返回 | 含义 |
| "status":"ok" | 正常，语义检索可用 |
| "status":"degraded" + "embedding_backend":"hash" | 已降级，检索质量不可信 |

降级时服务启动日志会打 ERROR 级说明与修复指引。修复方式： sh ./install.sh --model-only # 预下载 ONNX 模型（最常见原因：模型没下下来）或配置 embed_api_url 使用远程嵌入服务

若确实要在无语义能力下运行（如纯离线测试），显式接受： sh
export PANGU_ALLOW_HASH_FALLBACK=1

测试 sh pytest tests/ -v # 全量 pytest tests/ -v -m "not slow" # 跳过慢用例

CI：Python 3.10/3.11/3.12 矩阵 + 覆盖率门禁（.github/workflows/test.yml）。

文档

- 记忆系统内部原理 — 数据模型 / 存储格式 / 检索打分公式 / 衰减曲线，全链路文件行号级证据
- AGENTS.md — Agent 行为规范（写入即记 / 动手先查 / 状态外置 / 修复留痕）
- English overview: README_EN.md

License

见仓库许可文件。