cognitive-ai-memory

---

问题所在

每天早上，你的 AI Agent 都把你当成陌生人。相同的背景要重新解释，相同的偏好又被忘记。每次会话都从零开始。

大多数“记忆”工具只是给 Agent 加上向量数据库，就说大功告成——但那只是存储。它会囤积所有近似重复的内容，直到检索结果淹没在噪声中。就像给金鱼换了个更大的鱼缸。

YourMemory 与众不同：它像大脑一样运作，而非数据库。

flowchart LR
    A["🧠 You tell your<br/>AI something"] --> B["Extract durable<br/>facts"]
    B --> C["Dedup + embed<br/>+ graph-link"]
    C --> D[("Memory<br/>store")]
    D -->|"related facts pile up"| E["✨ Consolidate<br/>N → 1 summary"]
    D -->|"stale + unused"| F["📉 Decay<br/>+ prune"]
    D -->|"new session"| G["♻️ Recall<br/>hybrid + graph"]
    E --> D
    G --> H["🤖 Your agent<br/>picks up where<br/>it left off"]
    style D fill:#0a2540,stroke:#19cdff,color:#fff
    style E fill:#0c2b3a,stroke:#5eead4,color:#fff
    style H fill:#0c2b3a,stroke:#19cdff,color:#fff

---

✨ 与众不同之处

	功能	作用
🧠	记忆整合	当积累了足够多的相关事实时，它们会被压缩成一份简洁的摘要，原始内容则会归档。记忆会随着时间变得更精炼，而非更臃肿。
📉	生物性衰减	每条记忆都会遵循艾宾浩斯遗忘曲线逐渐衰减。陈旧、未使用的事实会淡去；重要且经常被回忆的事实则会保留。
🔗	实体图谱	记忆根据共同的人物、地点和概念建立关联——因此，回忆还会浮现出你忘了询问的内容。
♻️	经受上下文重置	上下文窗口压缩时，YourMemory 会交还工作上下文——无需重新阅读文件来弄清楚之前进行到哪里。
🔒	防篡改审计记录	每次读取／写入／删除都会记录在哈希链式账本中。修改任何一条记录都会导致链条断裂。
👥	团队记忆池	基于角色的共享记忆，让整个团队的 Agent 都能使用相同的机构知识，同时将私人记忆保密。
🛡️	内置数据权利保障	一条命令即可导出（访问权）和删除遗忘（清除），并提供符合 SOC 2 要求的控制措施。
🔌	原生支持 MCP，优先本地运行	可与 Claude、Cursor、Cline、Windsurf 或任何 MCP 客户端配合使用。完全在你的机器上运行——无需 API 密钥，数据不会离开你的系统。

一条命令即可安装。默认使用 DuckDB（零配置），团队可使用 Postgres + pgvector。

目录

• 🏆 基准测试
• 🚀 快速开始
• 🧠 记忆的工作原理
  • 整合
  • 衰减
  • 混合检索
• 🔒 信任与审计跟踪
• 👥 团队记忆池
• 🛡️ 数据权利与合规
• 🎛️ 仪表板
• 🔧 MCP 工具
• ⚡ 无需调用大模型即可提问
• 🔀 API 代理 — 保障记忆
• 🏗️ 架构与技术栈
• 🩺 故障排除
• 🤝 参与贡献

---

🏆 基准测试

三个外部数据集。每个数据均可独立复现——基准测试代码位于仓库中。完整方法见 BENCHMARKS.md。

LoCoMo-10 — 多会话对话记忆

xychart-beta
    title "Recall@5 · LoCoMo-10 (higher is better)"
    x-axis ["Mem0", "Zep Cloud", "Supermemory", "YourMemory"]
    y-axis "Recall@5 percent" 0 --> 70
    bar [18, 28, 31, 59]

召回率比 Zep Cloud 高 2 倍，覆盖全部 10 个样本。*Supermemory 和 Mem0 在基准测试中途耗尽了免费额度；分数根据全部 1,534 对数据计算。

LongMemEval-S — 500 个问题，每个问题约有 53 个干扰会话

这是长期记忆领域最难的标准基准测试。每个问题都埋藏在约 53 个会话中。

指标	分数
Recall@5（前 5 项中包含任一正确会话）	89.4%
Recall-all@5（前 5 项中包含所有正确会话）	84.8%
nDCG@5（排序质量）	87.4%

HotpotQA — 200 个多跳问题

系统	BOTH_FOUND@5
YourMemory（向量 + BM25 + 实体图）	71.5%
YourMemory（无实体边）	59.5%

实体图边带来 +12 个百分点——即使事实 2 与查询的嵌入相似度较低，也能从事实 1 遍历到事实 2。

文章：我使用艾宾浩斯遗忘曲线为 AI Agent 构建了记忆衰减机制

---

🚀 快速开始

Python 3.11–3.14。无需 Docker，也无需设置数据库。所有记忆都存储在本地 ~/.yourmemory/ 中。

pip install yourmemory
yourmemory-register <your-token>
yourmemory-setup

**获取令牌：**访问 yourmemoryai.xyz → 输入邮箱 → 使用 6 位验证码验证 → 复制令牌。

yourmemory-setup 会自动检测并配置 Claude Code、Claude Desktop、Cursor、Windsurf 和 Cline，随后询问要使用哪个后端：

• DuckDB — 零配置，单个本地文件（默认）
• Postgres — 用于共享环境 / 生产环境；需要提供 DATABASE_URL（需要 pgvector 扩展）

**可选 — 更智能的本地提取：**YourMemory 开箱即用，内置启发式规则。若要获得质量更高、完全本地运行的事实提取功能，请安装 Ollama，yourmemory-setup 会自动拉取模型（qwen2.5:7b，约 4.7 GB）。更倾向使用云端？设置 YOURMEMORY_EXTRACT_BACKEND=anthropic。

或者从二进制文件安装——无需 Python

不想使用 pip？从最新发布版本下载适用于你平台的独立二进制文件：

平台	文件
macOS（Apple Silicon）	yourmemory-macos-arm64.tar.gz
macOS（Intel）	yourmemory-macos-x86_64.tar.gz
Linux（x86-64）	yourmemory-linux-x86_64.tar.gz
Windows（x86-64）	yourmemory-windows-x86_64.exe.zip

# macOS / Linux — download, extract, run
tar -xzf yourmemory-macos-arm64.tar.gz
./yourmemory-macos-arm64 register <your-token>
./yourmemory-macos-arm64 setup
./yourmemory-macos-arm64            # start the server

一个可执行文件即可处理所有命令：register、setup、ask "<question>"、path，以及（不带参数时）启动服务。

完全独立且可离线运行——此二进制文件打包了 Python、所有依赖项，以及两个 ML 模型（嵌入模型 + spaCy）。首次运行时不会下载任何内容。代价是文件较大（约 2 GB）。只需运行一个命令即可自行构建——./build-binary.sh——构建工作流会自动生成多平台发布二进制文件。

🧠 记忆的运作方式

YourMemory 将记忆视为一个不断演化的系统——它会像大脑一样增长、整合、遗忘并建立联系。

整合 — N → 1

大多数记忆工具只会不断累积。YourMemory 会监测相关事实形成的群组；累积到一定数量后，将它们压缩成一份清晰的摘要，并归档原始内容（绝不删除，因此不会丢失任何信息）。

flowchart LR
    subgraph before [Related facts pile up]
        A1["Railway uses Nixpacks"]
        A2["Railway on Pro plan"]
        A3["Railway env vars hold<br/>the Postgres URL"]
        A4["Deploys on Railway<br/>with Postgres"]
    end
    before --> C{"cluster +<br/>LLM summarize"}
    C --> S["✨ Summary<br/>Deploys on Railway (Pro,<br/>Nixpacks) with Postgres<br/>via env vars"]
    C -.->|"archived, recoverable"| ARC[("archive")]
    style S fill:#0a2540,stroke:#5eead4,color:#fff
    style C fill:#0c2b3a,stroke:#19cdff,color:#fff

生产环境存储中的真实示例：444 条记忆 → 16 份摘要——知识不变，噪声却大幅减少。整合由事件触发（相关记忆积累到一定数量时触发），而不是盲目地每晚定时运行。

衰减 — 遗忘曲线

记忆强度会呈指数衰减。重要性和回忆频率会减缓衰减：

effective_λ  = base_λ × (1 − importance × 0.8)
strength     = clamp(importance × e^(−effective_λ × active_days) × (1 + recall_count × 0.2), 0, 1)

active_days 只统计你活跃的天数——休假不会导致记忆丢失。强度低于 0.05 的记忆会自动清除。每个类别的衰减速度各不相同：

类别	半衰期	最适用于
strategy	~38 天	有效的模式、架构决策
fact	~24 天	偏好、身份、稳定的知识
assumption	~19 天	推断出的上下文、不确定的信念
failure	~11 天	错误、错误的方法、特定于环境的问题

感知关联的清除： 如果某条衰减中的记忆仍有强度较高的图邻居，它就会被保留——即使很少被直接查询，承载重要信息的上下文也能留存。

混合检索 — 向量 + BM25 + 图

检索分两轮进行，既能呈现你要求的内容，也能呈现你忘记询问的内容：

flowchart LR
    Q["query"] --> R1["Vector + BM25<br/>hybrid search"]
    R1 --> R2["Graph expansion<br/>(what you forgot to ask)"]
    R2 --> S["rank by<br/>similarity × strength"]
    S --> OUT["🎯 Ranked memories"]
    style OUT fill:#0a2540,stroke:#19cdff,color:#fff

感知主题的去重会在每次存储前运行——它会嵌入每个句子的主题，因此 "Sachit uses DuckDB" 和 "YourMemory uses DuckDB" 会保持分开（实体不同），而 "YourMemory uses DuckDB" 和 "YourMemory stores data in DuckDB" 则会合并（实体相同）。没有硬编码的词表；适用于任何语言。

---

🔒 信任与审计跟踪

企业不会让不透明的黑箱存储自己的数据。因此，每项操作——读取、写入、更新、删除、整合——都会追加到基于哈希链且可检测篡改的审计日志中。

flowchart LR
    E0["GENESIS"] --> E1
    subgraph E1 [Event 1]
        H1["row_hash =<br/>sha256(prev + data)"]
    end
    E1 --> E2
    subgraph E2 [Event 2]
        H2["row_hash =<br/>sha256(#1.hash + data)"]
    end
    E2 --> E3
    subgraph E3 [Event 3]
        H3["row_hash =<br/>sha256(#2.hash + data)"]
    end
    E3 --> V{"GET /audit/verify"}
    V -->|chain intact| OK["✅ verified"]
    V -->|any row altered| BAD["❌ chain breaks<br/>at that row"]
    style OK fill:#0a2540,stroke:#5eead4,color:#fff
    style BAD fill:#3a0c14,stroke:#fb7185,color:#fff

每条记录都会记下时间戳、操作者用户及 Agent、操作、操作类型、目标记忆、来源（http 或 mcp）以及上一条记录的哈希。更改任何历史记录后，verify_chain() 都会精确指出哈希链从何处断裂。

GET  /audit            # browse the trail (filter by user / action / operation)
GET  /audit/verify     # cryptographically verify the chain is untampered
POST /audit/prune      # retention-based cleanup (90-day minimum, never lower)

审计日志采用故障开放模式——绝不会阻止记忆操作；同时会排除仪表板自身渲染循环产生的读取/列表事件，让审计跟踪保留有用信号，而非无关噪声。

---

👥 团队记忆池

让整个团队的 Agent 共用一个大脑，同时不泄露任何人的私人上下文。记忆分为共享（记忆池中的成员均可见）或私有（仅所有者可见）。

flowchart TB
    P(("🧠 Team Pool<br/>shared memory"))
    A["Alice's agent"] <-->|shared| P
    B["Bob's agent"] <-->|shared| P
    C["Carol's agent"] <-->|shared| P
    A -. private .-> AP["🔒 Alice-only"]
    B -. private .-> BP["🔒 Bob-only"]
    style P fill:#0a2540,stroke:#19cdff,color:#fff
    style AP fill:#0c1424,stroke:#5a6b80,color:#8294a8
    style BP fill:#0c1424,stroke:#5a6b80,color:#8294a8

系统会按每个 Agent 强制执行基于角色的访问控制——一位工程师的 Agent 学到的内容，整个团队都能立即受益；敏感上下文则仅限所有者访问。

POST   /pools                          # create a pool
POST   /pools/{id}/members             # add a member (with role)
POST   /pools/{id}/memories            # contribute a shared memory
POST   /pools/{id}/retrieve            # recall across the pool

---

🛡️ 数据权利与合规

因为存储真实数据的记忆，需要具备相应的控制措施，才能让人放心使用：

权利	端点	功能
访问（DSAR 导出）	GET /users/{id}/export	完整导出为某位用户存储的所有内容
删除（被遗忘权）	DELETE /users/{id}/memories	一条命令清除某位用户的所有记忆
可移植性	POST /users/{id}/import	重新导入之前导出的数据
可恢复性	GET /users/{id}/archive	取回整合时归档的原始内容

结合基于哈希链的审计跟踪和 90 天的最低保留期限，这些措施直接对应于 SECURITY.md（符合 SOC 2 要求）中记录的控制措施。

---

🎛️ 仪表板

内置两种浏览器 UI——无需额外设置，启动服务时会自动运行。

记忆仪表板 — http://localhost:3033/ui

完整的读写视图，包含 记忆 · 审计 · 池 标签页：统计栏（强 · 衰减中 · 即将剪枝）、按 Agent 划分的标签页、带实时强度条的记忆卡片、类别筛选器、审计记录和记忆池管理。

图谱可视化 — http://localhost:3033/graph

交互式力导向图，展示记忆之间的关联 — 根记忆以亮色节点显示，邻近节点按类别着色，边的粗细表示关联强度。拖动、缩放并点击任意节点，即可查看完整内容。

http://localhost:3033/graph?memoryId=42&userId=alex&depth=2

---

🔧 MCP 工具

三个工具，由你的 AI 自动调用。

工具	AI 何时调用	功能
recall_memory(query, current_path?)	每项任务开始时	按相似度 × 衰减强度排列并呈现记忆；对路径匹配的记忆进行空间加权
store_memory(content, importance, category?, context_paths?)	学到新内容后	生成嵌入、去重并存储，同时应用衰减；可选标记文件/目录路径
update_memory(id, new_content, importance)	已存储的信息过时时	重新生成嵌入并替换；将更改记录到审计记录中

# Store with spatial context
store_memory(
    "Alex prefers tabs over spaces in Python",
    importance=0.9, category="fact",
    context_paths=["/projects/backend"],
)

# Next session — spatial boost fires when working in that directory
recall_memory("Python formatting", current_path="/projects/backend")
# → {"content": "Alex prefers tabs over spaces in Python", "strength": 0.87}

---

⚡ 无需调用大模型即可回答

唯一能够不调用任何大模型 API就回答问题的记忆系统：

yourmemory ask "what database does this project use"
# → YourMemory uses DuckDB locally and Postgres in production.

yourmemory ask "how do I fix a kubernetes deployment"
# → Not enough memory context to answer without an LLM.

记忆足够可靠时，系统会立即回答 — 不消耗令牌、不产生云端成本、没有延迟。若记忆不足，则会明确拒答，而不是编造内容。你的查询绝不会离开本机。

---

🔀 API 代理 — 确保记忆发挥作用

MCP 工具由 AI 自行决定是否调用。API 代理消除了这种不确定性 — 它会拦截每次大模型调用，自动注入相关记忆，并且无需配置模型即可处理 store_memory / update_memory。

启动服务（yourmemory），然后将客户端指向 localhost:3033：

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-ant-...",
    base_url="http://localhost:3033/proxy/anthropic",
    default_headers={"X-YourMemory-User": "alex"},  # per-user memory
)

# Memory is injected automatically — no other changes needed
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What database do I use?"}],
)

OpenAI 也可通过 base_url="http://localhost:3033/proxy/openai" 以相同方式使用。

---

🏗️ 架构与技术栈

flowchart LR
    C["Your AI client<br/>Claude · Cursor · any MCP"] <--> Y["🧠 YourMemory"]
    Y --> M[("Memory<br/>store")]
    Y --> A[("Audit<br/>ledger")]
    style Y fill:#0a2540,stroke:#19cdff,color:#fff
    style M fill:#0c1a2c,stroke:#5eead4,color:#fff
    style A fill:#0c1a2c,stroke:#5eead4,color:#fff

组件	用途
DuckDB	默认向量存储 — 无需设置，原生支持余弦相似度
PostgreSQL + pgvector	可选 — 适用于团队或大型数据集
NetworkX	默认图后端（~/.yourmemory/graph.pkl）
Neo4j	可选图后端
sentence-transformers	本地嵌入（multi-qa-mpnet-base-dot-v1，768 维）
spaCy	用于去重和实体提取的本地 NLP
APScheduler	自动衰减 + 剪枝

---

🩺 故障排除

写入卡住 / 超时（DuckDB 单写入器锁）。 如果 MCP 服务和 HTTP 服务同时运行，它们会争用 DuckDB 写入锁。解决方法：

pkill -f yourmemory 2>/dev/null || true
rm -f ~/.yourmemory/memories.duckdb.wal ~/.yourmemory/memories.duckdb.lock 2>/dev/null || true
# restart your client

同时运行 Claude Desktop（MCP）和 Claude Code（钩子）？请改用 SQLite — 它可以妥善处理并发读写： DATABASE_URL=sqlite:///~/.yourmemory/memories.db

---

🤝 参与贡献

欢迎提交 PR — 请参阅 CONTRIBUTORS.md。

📚 数据集参考

• LoCoMo — Maharana 等人（2024）
• LongMemEval — Wu 等人（2024）
• HotpotQA — Yang 等人（2018）

📄 许可证

版权所有 2026 Sachit Misra — 根据 CC-BY-NC-4.0 许可。

可免费用于个人用途、教育、学术研究和开源项目。 商业用途需要另行签署书面协议 → [email protected]