盘古（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），并在防火墙/安全组只放行反向代理端口。

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

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 加速镜像：
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   # 内网/弱网：从本地文件装模型

手动安装

# 安装（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/音频/图片抽取、「语音转写」管音频转写 —— 两者都默认关闭）：
# 无 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。

# 方式一：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

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 配置：
```
{ "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）：

curl -fsSL https://raw.githubusercontent.com/Mlte0907/dsh-pangu/main/install.sh | bash
./install.sh tui                       # 换 profile：先 clone 插件仓再 ./install.sh <profile>

盘古与 DSH 同机时也可以让盘古的安装脚本顺带拉取安装：

cd ~/pangu && ./install.sh --dsh-plugin     # 拉取到 ~/.dsh-pangu 并安装

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

注：cordis.patch.yml 的 HMR 在 web 实例不生效，改后需重启 DSH。

# 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）。

自查一行命令：

curl -s http://127.0.0.1:19529/health

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

降级时服务启动日志会打 ERROR 级说明与修复指引。修复方式：

./install.sh --model-only     # 预下载 ONNX 模型（最常见原因：模型没下下来）
# 或配置 embed_api_url 使用远程嵌入服务

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

export PANGU_ALLOW_HASH_FALLBACK=1

测试

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

见仓库许可文件。

Name		Name	Last commit message	Last commit date
.github		.github
deploy		deploy
docs		docs
experimental		experimental
monitoring		monitoring
pangu		pangu
plugins		plugins
scripts		scripts
systemd		systemd
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.mimosaignore		.mimosaignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
DEAD_CODE_REPORT.md		DEAD_CODE_REPORT.md
DEPLOY.md		DEPLOY.md
Dockerfile		Dockerfile
MAINTAINERS.md		MAINTAINERS.md
README.md		README.md
README_EN.md		README_EN.md
docker-compose.yml		docker-compose.yml
env.example		env.example
install.sh		install.sh
mkdocs.yml		mkdocs.yml
pangu.spec		pangu.spec
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements-docs.txt		requirements-docs.txt
requirements.txt		requirements.txt
start.sh		start.sh
stop.sh		stop.sh
uv.lock		uv.lock

Navigation Menu

Repository navigation

About

Repository files navigation

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

三步跑起来

核心能力

安装（详细）

一键安装（推荐）

云端部署

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

手动安装

Docker

接入 DeepSeek Harness（可选插件）

记忆是怎么工作的

配置

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

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

测试

文档

License

About

Releases

Packages

Contributors

Languages

包	引用位置	是否影响启动
`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` 默认值	否

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

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

Latest commit

History

Folders and files

Repository files navigation

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

三步跑起来

核心能力

安装（详细）

一键安装（推荐）

云端部署

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

手动安装

Docker

接入 DeepSeek Harness（可选插件）

记忆是怎么工作的

配置

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

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

测试

文档

License

About

Topics

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages