GraphMemory

双时态 AI 记忆系统 — 给 AI 代理一个会积累、会遗忘、会随时间变化的长期记忆库。

A bitemporal memory service for AI agents: facts with two time axes, a six-variable importance/decay model, time-graded recall, TTL-based expiry, deduplication, and a competitive retrieval layer on top of Graphiti (temporal knowledge graph) + PostgreSQL/pgvector + Redis.

设计思路与完整开发记录见 docs/DESIGN_ZH.md。

67 秒 · 小鱼配音 · 中文字幕 · 直接下载

                     ┌─────────────────────────────┐
   Agent / MCP 客户端 │  graphmemory (FastAPI :8000) │
                     │  /add  /search  /chat  /decay│
                     └───────┬──────────┬──────────┘
                             │          │
                  ┌──────────▼──┐  ┌────▼────────────┐
                  │ Neo4j 5.26  │  │ PostgreSQL+pgvec │
                  │ 时序知识图谱 │  │ fact_state/state │
                  └─────────────┘  │ episodes/ledger  │
                                   └────┬────────────┘
                                   ┌────▼───────┐
                                   │  Redis 7   │
                                   └────────────┘

• Neo4j：实体/关系（RELATES_TO 事实边 + MENTIONS 提及边）
• PostgreSQL：双时态事实台账、六变量状态、原文账本、行为账本、墓碑
• Redis：检索缓存、会话状态

• Python ≥ 3.10
• Docker + Docker Compose（跑 Neo4j / PostgreSQL / Redis）

cp .env.example .env          # 填好数据库密码与 LLM key
docker compose up -d

python -m venv .venv && . .venv/bin/activate
pip install -e .
psql "postgresql://graphmemory:${POSTGRES_PASSWORD}@localhost:5432/graphmemory" \
     -f scripts/init_db.sql
psql ... -f scripts/upgrade_chat_memory.sql

uvicorn graphmemory.main:app --host 127.0.0.1 --port 8000
# 管理台: http://127.0.0.1:8000/ui

# 写入
curl -s -X POST localhost:8000/api/v1/memory/add \
  -H 'Content-Type: application/json' \
  -d '{"content":"用户A 2026-10-29 答应周六一起去看海","user_id":"100000002",
       "source_type":"remembered_fact","raw_quote":"周六一起去看海"}'

# 检索
curl -s -X POST localhost:8000/api/v1/memory/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"周末约了什么","user_id":"100000002","top_k":3}'

# 手动跑一轮衰减
curl -s -X POST localhost:8000/api/v1/memory/decay

mcp_server.py 提供 stdio MCP server：

{
  "command": "python",
  "args": ["/path/to/graphmemory/mcp_server.py"],
  "env": {
    "GRAPHMEMORY_BASE_URL": "http://127.0.0.1:8000/api/v1/memory",
    "GRAPHMEMORY_AGENT_ID": "my-agent"
  }
}

可用工具：add_memory、search_memory、memory_stats、list_episodes、get_timeline、list_facts、chat、memory_dedupe、memory_forget、get_status、list_episodes。

所有配置走环境变量（见 .env.example）：

写库时自动按内容分类并设置有效期（见 src/graphmemory/recall/validity.py、time_gradient.py）：

到期后先隐藏、宽限 1 天物理删除（原文账本 episodes 永久保留）。

本仓库不包含任何真实用户数据、API key、Cookie 或服务器凭据：

• 所有密钥仅从环境变量读取，.env 已被 .gitignore
• 示例中的 QQ 号/用户名均为占位符（100000001、用户A）
• 不含聊天记录、用户档案、数据库转储
• 详见 docs/PRIVACY.md

部署前必改：数据库密码、API_KEY、SSH/端口暴露面；不要把 .env 提交进仓库。

pip install -e ".[dev]"
pytest

scripts/verify_chat_memory.py 提供一个端到端冒烟脚本（需服务已启动）。

src/graphmemory/
├── main.py              # FastAPI 入口 + 后台衰减/时效清理循环
├── config.py            # 环境变量配置
├── core/graphiti_client.py
├── api/{routes,schemas}.py
├── policy/              # 冲突裁决 / 置信度 / 去重
├── procedural/          # 程序性记忆
├── system2/             # 多工具编排
├── recall/              # ★ 六变量衰减 / 竞争检索 / 时间梯度 / TTL / 去重
└── web/                 # 管理台
mcp_server.py            # MCP stdio server
scripts/                 # schema 迁移、冒烟、工具脚本
docs/                    # 设计文档

以下属于特定部署环境的集成，不在本仓库，可按需自行实现：

• 桌面控制台小组件（原作者本地组件，不属于本项目）
• QQ / NapCat / 其他 IM 的适配插件（含「每轮自动记忆注入」钩子）
• 私有的提示词/人设与业务数据

MIT — 见 LICENSE。

最后，我们誓死践行开源精神。