🧠 Immortal Memory

本地优先的个人记忆操作系统：把你的 AI 对话、文档、会议、知识、偏好和决策痕迹，沉淀成一个可被 Codex、Claude Code、MCP、HTTP Agent 调用的长期记忆层。

🚀 快速开始 · 🧩 它能做什么 · 📋 使用-sop · 🤖 接入其他-agent · 🔒 隐私边界 · 🗺️ 路线图

👋 这是什么？

Immortal Memory 是一个给 AI 重度用户准备的“个人记忆底座”。

今天你可能同时在用 Codex、Claude Code、ChatGPT、Cursor、飞书、会议转录、本地文档、知识库和各种脚本工具。问题是：每个 Agent 都只知道眼前这一小段上下文，不知道你过去说过什么、做过什么决定、喜欢什么表达方式、有哪些长期项目、哪些人和你有关、哪些内容是你本人说的，哪些只是别人说的。

更麻烦的是，很多重要语料会丢：

💬 AI 对话被误删，历史判断消失
📄 文档散在不同目录，没人长期整理
🎙️ 会议纪要没人沉淀，过几天就找不到
🧠 个人偏好和决策标准反复告诉不同 Agent
🧹 原始语料里混着别人的话，AI 清洗后容易污染“我的画像”

Immortal Memory 想解决的不是“做一个漂亮看板”，而是：

先把个人数字痕迹保存下来，再把它清洗成可信记忆，最后让任何本地 Agent 在需要时都能安全调用。

🧩 它能做什么？

1. 🛟 防丢失：把重要语料收进本地保险库

所有数据默认进入本机的：

~/.immortal/

这里可以持续保存：

AI 对话导出
本地 Markdown / TXT / JSON / 文档摘要
会议纪要和转录文本
飞书 / Lark 相关数据
每日新增记录
生成后的画像、人物索引、质量报告、短期任务上下文
可恢复的便携备份

这个目录不会被提交到 GitHub。开源仓库只放代码、适配器和文档。

2. 🧼 防污染：区分“我说的”和“别人说的”

个人记忆最危险的地方不是数据少，而是数据脏。

比如一段聊天里可能同时包含：

用户本人表达的观点
同事说的话
AI 总结出来的猜测
外部文章引用
项目事实
待确认的传闻

Immortal Memory 会尽量做归因清洗，把内容分层：

类型	处理方式
本人观点 / 偏好	可进入长期画像
他人发言	进入人物或关系记录，不污染本人画像
项目事实	进入项目记忆
外部引用	保留来源，不当成本人观点
低置信内容	标记为待确认或降权

目标不是把所有内容都塞进一个“大 prompt”，而是让记忆越来越可信。

3. 🧪 蒸馏：把原始材料变成可用的长期记忆

系统会从原始语料中生成多层产物：

🧬 长期个人画像：你的目标、偏好、表达风格、工作方式
🧠 思维模型画像：你常用的判断标准、决策方式、反复出现的原则
👥 人物索引：与你有关的人、他们的角色、别名、关系证据
🕸️ 关系证据：人、项目、话题之间的关联
📅 时间线：每天发生了什么、积累了什么
✅ 质量报告：记忆库是否健康、是否有污染风险
🧾 每日摘要：当天新增内容和变化
🤖 任务上下文：例如写稿审稿、项目推进、会议复盘、商务判断

4. 🤖 给其他 Agent 调用

Immortal Memory 不要求其他 Agent 直接读完整保险库。

它提供两个统一入口：

immortal-memory agent-context "当前任务" --print
immortal-memory task-compile "当前任务" --mode auto

其他 Agent 只需要把自己的任务告诉它，就能拿到一份“任务相关的记忆包”或一个短期 session。这样既能让 Agent 更懂你，又不会把所有私人原始数据一次性暴露出去。

5. 🔌 支持 CLI / HTTP / MCP

你可以用三种方式接入：

方式	适合谁
CLI	Codex、Claude Code、本地脚本
HTTP	自己写的 Agent、浏览器工具、本地服务
MCP	支持 MCP 的客户端或 IDE

🚀 快速开始

1. 克隆项目

git clone https://github.com/HeiGeAi/immortal-memory.git
cd immortal-memory

2. 安装到本机

python3 install.py \
  --owner-display-name "Your Name" \
  --alias "YourAlias" \
  --install-codex-adapter \
  --install-claude-adapter

安装完成后，会创建：

~/.local/bin/immortal-memory
~/.local/share/immortal-memory/
~/.immortal/

如果你的 shell 找不到 immortal-memory，把下面这一行加入 ~/.zshrc 或 ~/.bashrc：

export PATH="$HOME/.local/bin:$PATH"

3. 跑一次训练流程

immortal-memory train --smoke --build-role --goal "writing review" --mode writer

第一次可以先用 --smoke 验证流程能跑通。--build-role 现在是兼容旧命令的名字，实际会生成短期任务上下文，不会默认安装长期 skill。后续接入真实数据后，再跑完整训练。

4. 打开本地看板

immortal-memory agent-factory

默认打开：

http://127.0.0.1:8765/

看板里可以观察：

记忆库状态
最近采集情况
画像与人物索引
时间线
质量报告
Agent Bridge 入口
最近生成的任务上下文

📋 使用 SOP

下面是一套比较稳的使用流程。普通用户照着做，就能理解这个工具怎么落地。

Step 0：先明确身份

初始化时告诉系统：

你叫什么
常用别名是什么
哪些账号属于你
哪些账号不是你

示例：

immortal-memory init \
  --owner-display-name "Your Name" \
  --alias "YourAlias" \
  --primary-account "your-main-account"

这一步很重要，因为后面清洗“本人语料”和“非本人语料”都依赖身份边界。

Step 1：先采集，不急着训练

建议先把能收集的材料放进本地保险库：

~/.immortal/

可以逐步接入：

AI 对话导出
本地文档
会议纪要
飞书 / Lark 数据
手写笔记
项目复盘

原则是：先保证不丢，再逐步清洗。

Step 2：执行清洗和蒸馏

immortal-memory train --build-role --goal "writing review" --mode writer

它会尽量完成：

采集 → 清洗 → 归因 → 画像 → 人物索引 → 质量报告 → 看板 → 任务上下文生成

Step 3：检查质量

immortal-memory health --max-age-hours 48
immortal-memory quality

你应该重点看：

最近有没有采集
画像是否生成
人物索引是否合理
质量分是否异常
是否出现明显“别人说的话被当成我说的”

Step 4：开启每日自动化

immortal-memory daily-install
immortal-memory daily-status

开启后，系统会在后台定期执行采集、清洗、蒸馏、摘要和看板更新。

如果你已经接入 Get 笔记，还可以让它每天自动生成一篇“昨天我做了什么”的日记，并归入 Get 笔记知识库：

mkdir -p ~/.getnote
cat > ~/.getnote/config.json <<'JSON'
{
  "api_key": "你的 Get 笔记 API Key",
  "client_id": "你的 Get 笔记 Client ID"
}
JSON

immortal-memory getnote-diary --yesterday
immortal-memory getnote-status

之后每日自动化会自动执行：

采集/清洗/摘要 → 生成昨日行动日记 → 同步到 Get 笔记 → 加入知识库

历史日记会按 Get 笔记 API 额度分批补齐。系统只同步“有有效摘要的日期”，不会把无记录的空日记继续塞进知识库。

如果你不想继续自动跑：

immortal-memory daily-uninstall

Step 5：让其他 Agent 调用

最简单的一句话：

immortal-memory agent-context "我现在要做的任务" --print

例如：

immortal-memory agent-context "帮我审一篇产品方案，判断表达是否符合我的风格" --print

返回的内容就是给其他 Agent 使用的任务级记忆包。

Step 6：定期备份

immortal-memory export
immortal-memory backup-status

建议把导出的备份放到你信任的位置，例如：

本机外置硬盘
私有 NAS
加密云盘
私有对象存储

不建议把完整私人原始库直接放进公开仓库。

🤖 接入其他 Agent

最稳妥的复制粘贴提示词

把下面这段给 Codex、Claude Code 或任何能运行本地 shell 的 Agent：

你可以使用本机的 Immortal Memory 作为用户长期记忆层。

请先读取：
~/.immortal/agent/ENTRY.md

然后根据当前任务运行：
immortal-memory agent-context "<把当前任务写在这里>" --print

使用返回的 task-local context 来理解用户的偏好、项目背景、人物关系和历史决策。
不要直接读取 ~/.immortal/ 下的原始保险库，除非用户明确要求。
不要把返回内容当作绝对事实；如果上下文里标注了低置信或待确认，需要谨慎处理。

Codex

安装时加上：

python3 install.py --install-codex-adapter

之后 Codex 可以通过本地 skill 调用 Immortal Memory。

Claude Code

安装时加上：

python3 install.py --install-claude-adapter

Claude Code 可以通过同样的入口读取任务相关上下文。

通用 CLI Agent

immortal-memory agent-entry
immortal-memory agent-context "current task" --print
immortal-memory recall "某个历史决策或主题"

🌐 HTTP / MCP 接入

HTTP Agent Bridge

启动本地 HTTP 服务：

immortal-memory agent-http --host 127.0.0.1 --port 8799

可用接口：

GET  /health
GET  /agent-entry
GET  /api/agent-entry
POST /agent-context   { "task": "..." }
POST /recall          { "query": "..." }

调用示例：

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

curl -s http://127.0.0.1:8799/agent-context \
  -H "Content-Type: application/json" \
  -d '{"task":"review this product plan"}'

如果你要绑定非本机地址，必须加 token：

immortal-memory agent-http --host 0.0.0.0 --port 8799 --token "$IMMORTAL_BRIDGE_TOKEN"

然后请求时带上：

curl -H "Authorization: Bearer $IMMORTAL_BRIDGE_TOKEN" \
  http://127.0.0.1:8799/api/agent-entry

MCP Server

给支持 MCP 的客户端加入：

{
  "mcpServers": {
    "immortal-memory": {
      "command": "immortal-memory",
      "args": ["agent-mcp"]
    }
  }
}

暴露的工具：

Tool	用途
`immortal_agent_entry`	返回稳定接入说明
`immortal_agent_context`	按当前任务生成上下文包
`immortal_recall`	按主题检索历史记忆

调用审计

HTTP 和 MCP 调用都会写入本地审计日志，但不会记录完整上下文内容：

immortal-memory agent-audit --limit 20

日志位置：

~/.immortal/agent/access.log
~/.immortal/agent/access_latest.json

🏗️ 工作流长什么样？

flowchart LR
  A["AI 对话 / 文档 / 会议 / 飞书 / 本地文件"] --> B["本地保险库 ~/.immortal"]
  B --> C["清洗与归因"]
  C --> D["长期画像"]
  C --> E["人物索引"]
  C --> F["关系证据"]
  C --> G["质量报告"]
  D --> H["Agent Bridge"]
  E --> H
  F --> H
  G --> H
  H --> I["Codex"]
  H --> J["Claude Code"]
  H --> K["HTTP Agent"]
  H --> L["MCP Client"]

核心思想很简单：

原始数据不要直接喂给 Agent
先保存，再清洗，再蒸馏
最后按任务给 Agent 一小包可信上下文

📦 项目结构

immortal-memory/
├── install.py                    # 一键安装器
├── core/                         # 记忆内核
│   ├── immortal.py               # CLI 入口
│   ├── agent_bridge.py           # CLI / 文件 Agent Bridge
│   ├── agent_bridge_server.py    # HTTP / MCP Agent Bridge
│   ├── collect.py                # 多源采集
│   ├── profile.py                # 长期画像生成
│   ├── people_index.py           # 人物索引
│   ├── task_compile.py           # 短期任务上下文生成
│   ├── getnote_sync.py           # Get 笔记每日行动日记同步
│   ├── role_distill.py           # 高频稳定流程的显式角色晋升
│   └── profile_review.py         # 本地看板服务
├── adapters/
│   ├── codex/                    # Codex 适配器
│   └── claude-code/              # Claude Code 适配器
├── docs/                         # 产品 / 架构 / 隐私 / 适配器文档
├── examples/
│   ├── agent-handoff.md
│   ├── http-client.sh
│   └── mcp-config.json
└── scripts/
    ├── private_scan.py           # 发布前数据泄露扫描
    └── smoke_test.sh             # Smoke 测试

🔒 隐私边界

这个仓库是开源空壳，不包含任何用户私人数据。

不要提交：

~/.immortal/
原始聊天记录
企业文档
会议转录
飞书 / Lark 数据
生成后的私人画像
角色证据
API Key / App Secret / Token
导出备份

发布前运行：

python3 scripts/private_scan.py .
bash scripts/smoke_test.sh

设计原则：

🔐 数据默认留在本机
🧾 Agent 调用有审计
🧩 其他 Agent 只拿任务相关上下文
🚫 不默认暴露完整原始库
🧼 个人画像需要尽量防止非本人语料污染

✅ 当前状态

当前版本是 v0.1 empty shell，重点是把产品骨架跑通。

已包含：

✅ 本地 memory core
✅ 安装器
✅ Codex adapter
✅ Claude Code adapter
✅ CLI Agent Bridge
✅ HTTP Agent Bridge
✅ MCP Agent Bridge
✅ Agent Bridge 调用审计
✅ 本地看板
✅ 短期任务上下文生成
✅ 显式角色晋升基础流程
✅ 每日自动化命令
✅ 备份 / 恢复检查
✅ smoke test
✅ private scan
✅ 产品、架构、隐私文档

还在继续增强：

⏳ 更强的 connector SDK
⏳ 更细的权限 scope
⏳ 更强的“非本人语料污染”检测
⏳ 更多 MCP 客户端兼容测试
⏳ 更丝滑的新用户引导
⏳ 云文档 / 会议 / 本地文件采集器增强

🗺️ 适合谁？

这个项目适合：

AI 重度用户
经常切换多个 Agent 的人
想保留 AI 对话资产的人
想训练个人数字分身 / 工作代理的人
想让 Codex、Claude Code、MCP 工具更懂自己的人
对隐私敏感，希望数据默认留在本地的人

不适合：

想要开箱即用云 SaaS 的用户
不愿意在本地配置命令行的人
希望 AI 完全自动替代本人做高风险决策的人

❓常见问题

这是一个知识库吗？

不只是知识库。普通知识库偏“存资料和检索资料”，Immortal Memory 更关注“把个人长期痕迹清洗成 Agent 可用的上下文”。

它能完全替代我本人吗？

不能，也不应该这样承诺。

它更适合做：

记住你的历史偏好
帮你回忆旧决策
模仿你的写作和判断倾向
给其他 Agent 提供背景
为特定任务生成短期上下文
把高频稳定流程显式晋升为角色 Agent

高风险、不可逆、强责任决策仍然需要本人确认。

数据会上传吗？

默认不会。数据留在本地 ~/.immortal/。如果你接入第三方 API 或云同步，那是你自己额外配置的范围。

为什么不让 Agent 直接读取原始数据？

因为原始数据太大、太脏、太敏感。更稳的方式是：先清洗和蒸馏，再按任务生成小范围上下文。

可以给团队用吗？

可以，但建议每个人都有自己的本地保险库和身份配置。团队共享部分应该通过明确的项目资料或受控 connector 进入，不要把个人完整原始库混在一起。

🧪 开发者验证

python3 -m py_compile core/*.py
python3 scripts/private_scan.py .
bash scripts/smoke_test.sh

如果要检查 Agent Bridge：

immortal-memory agent-http --host 127.0.0.1 --port 8799
curl -s http://127.0.0.1:8799/health

🌍 English Summary

Immortal Memory is a local-first personal memory layer for AI agents. It captures your digital traces from AI conversations, documents, meetings, and local tools into a private vault, cleans and attributes them, distills structured memory, and exposes task-scoped context to Codex, Claude Code, HTTP agents, or MCP clients.

Private data stays in ~/.immortal/. This repository contains only the open-source shell: core code, adapters, docs, and validation scripts.

git clone https://github.com/HeiGeAi/immortal-memory.git
cd immortal-memory
python3 install.py --owner-display-name "Your Name" --alias "YourAlias"
immortal-memory agent-context "current task" --print

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
adapters		adapters
core		core
docs		docs
examples		examples
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
install.py		install.py
manifest.json		manifest.json
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

🧠 Immortal Memory

👋 这是什么？

🧩 它能做什么？

1. 🛟 防丢失：把重要语料收进本地保险库

2. 🧼 防污染：区分“我说的”和“别人说的”

3. 🧪 蒸馏：把原始材料变成可用的长期记忆

4. 🤖 给其他 Agent 调用

5. 🔌 支持 CLI / HTTP / MCP

🚀 快速开始

1. 克隆项目

2. 安装到本机

3. 跑一次训练流程

4. 打开本地看板

📋 使用 SOP

Step 0：先明确身份

Step 1：先采集，不急着训练

Step 2：执行清洗和蒸馏

Step 3：检查质量

Step 4：开启每日自动化

Step 5：让其他 Agent 调用

Step 6：定期备份

🤖 接入其他 Agent

最稳妥的复制粘贴提示词

Codex

Claude Code

通用 CLI Agent

🌐 HTTP / MCP 接入

HTTP Agent Bridge

MCP Server

调用审计

🏗️ 工作流长什么样？

📦 项目结构

🔒 隐私边界

✅ 当前状态

🗺️ 适合谁？

❓常见问题

这是一个知识库吗？

它能完全替代我本人吗？

数据会上传吗？

为什么不让 Agent 直接读取原始数据？

可以给团队用吗？

🧪 开发者验证

🌍 English Summary

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages