graphmemory - 为 AI 代理设计的双时态长期记忆服务

graphmemory 是一个面向 AI 代理的长期记忆服务。它要解决的问题是：多数代理的「记忆」要么是塞进上下文窗口的对话片段，要么是一张只增不减的向量表，既分不清「这件事当时是什么样」和「后来被改成了什么样」，也不会随时间自然淡出。graphmemory 的做法是给每条事实配两条时间轴，再叠加一套带时间梯度的衰减与过期机制。据项目自述，它适合需要跨会话记住用户偏好、承诺、身份信息与临时状态的代理场景，也适合想研究「机器遗忘」如何工程化落地的开发者。

维护者与状态

项目由 gh9ko8y 维护，仓库创建于 2026-10-30，最后一次提交同样在 2026-10-30，属于刚公开不久的新项目。事实表显示，该项目尚无正式 release，因此没有可引用的版本号与发布说明，使用时应以仓库主干代码为准。截至 2026-11-08，仓库星标数为 201。

主要能力

以下能力均据项目 README 自述整理，未做独立验证：

• 双时态事实：每条事实同时记录「有效时间」（valid_from / valid_until）与「记录时间」（tx time），据项目说明，这样可以回答「当时是什么」以及「后来改了什么」两类问题。
• 六变量衰减模型：以 S（意义）、D（细节）、R（检索难度）、E（情绪）、C（巩固）、I（干扰）六个变量描述记忆状态，遗忘表现为「降级」而非直接删除。
• 时间梯度：按 1 天、3 天、7 天、10 天、2 周、3 周、1 月、3 月、半年、1 年等档位，越久远的事实细节上限越低、检索难度下限越高、表述口径越不确定。
• 时效性 TTL：写入时按内容自动分类并设定有效期，例如临时状态 1 天、动作 3 天、事件 7 天、承诺 10 天、普通事实 14 天、偏好永久、身份陈述 3 年、不可更改事实永久。
• 到期确认：带明确日期的约定先存 due_at，到期后进入「待确认」状态，确认之后再开始计时效。
• 动态年龄：年龄只存出生锚点，检索时实时计算，因此同一份数据在不同年份查询会得到对应年份的岁数。
• 竞争检索：以激活度、匹配度、资源适配度计算得分，经相对阈值筛选后取 Top-K，命中会反过来巩固记忆。
• 去重与遗忘工具：提供 memory_dedupe 做语义重复扫描，memory_forget 做墓碑式删除并保留原文账本。
• 图谱连通性：以渗流视角给出平均度 ⟨k⟩=2E/N、巨分量占比与孤立实体名单。
• 原文账本：episodes 表只追加不更新，可回溯「当时到底说了什么」。
• MCP 与 Web 管理台：内置 MCP server，任何支持 MCP 的代理可直接调用；同时自带极简 Web GUI（/ui）与 REST API。

架构上，项目以 FastAPI 服务为入口，Neo4j 存实体与关系，PostgreSQL 配合 pgvector 存双时态事实台账、六变量状态、原文账本与墓碑，Redis 负责检索缓存与会话状态。

使用入口

仓库地址：gh9ko8y/graphmemory。

据 README，运行前置条件为 Python ≥ 3.10 以及 Docker + Docker Compose。典型流程是：复制 .env.example 并填写数据库密码与 LLM key，用 docker compose up -d 拉起 Neo4j / PostgreSQL / Redis，创建虚拟环境后 pip install -e .，再用 scripts/init_db.sql 与 scripts/upgrade_chat_memory.sql 初始化 schema，最后以 uvicorn 启动服务：

uvicorn graphmemory.main:app --host 127.0.0.1 --port 8000

写入与检索通过 REST 接口完成，例如向 /api/v1/memory/add 提交 content、user_id、source_type 与 raw_quote，向 /api/v1/memory/search 提交 query、user_id 与 top_k；/api/v1/memory/decay 可手动触发一轮衰减。以 MCP 方式接入时，README 给出的配置是让客户端以 stdio 启动 mcp_server.py，并通过环境变量 GRAPHMEMORY_BASE_URL 与 GRAPHMEMORY_AGENT_ID 指向服务地址与代理标识；可用工具包括 add_memory、search_memory、memory_stats、list_episodes、get_timeline、list_facts、chat、memory_dedupe、memory_forget、get_status 等。

配置全部走环境变量，除数据库连接外，还需要 OpenAI 兼容的 Embedding 接口与用于事实抽取的 LLM 接口；API_KEY 非空时，/api 请求需携带 X-API-Key。

许可与限制

许可证为 MIT，可查阅仓库中的 LICENSE 文件。

据项目说明，仓库不包含任何真实用户数据、API key、Cookie 或服务器凭据，示例中的账号与用户名均为占位符；部署前需要修改数据库密码、API_KEY 与端口暴露面，且不应把 .env 提交进仓库。README 也明确列出未包含的内容：桌面控制台小组件、QQ / NapCat 等即时通讯软件的适配插件（含每轮自动记忆注入钩子）、以及私有的提示词、人设与业务数据，这些都需要使用者按自身环境另行实现。此外，项目依赖 Neo4j、PostgreSQL 与 Redis 三套外部服务，属于偏重的部署形态；由于尚无正式 release，接口与 schema 存在随主干变动的可能，升级前应留意 scripts/ 下的迁移脚本。