内容
# mcp-agent-memory
**用于LLM代理的结构化、持久工作内存，由Neo4j支持。** 一个MCP服务器，允许代理在多个独立会话中积累它对某个主题的了解，并在重新进入时回忆和推理这些知识，同时由工具强制执行图的完整性，而不是指令。没有原始写入；代理无法物理地损坏自己的内存。
大多数内存工具为代理提供了一堆平面的笔记。而这个工具提供了一个**时间有序**的内存：每个会话都是一个`Encounter`，这些`Encounter`按时间顺序链接，代理记录的所有内容都挂靠在它学习的会话上。这种有序结构使代理能够回顾自己的历史——“我上次了解到什么，还有什么仍未解决”——而无需在每个会话中重新推导。
> 在其底层，这是一个**遭遇顺序语义图**：一个过程主干（遭遇链）承载着一个语义层（观察、问题、假设、概念）和一个引用层（指向其读取的来源的书签）。您不需要这种框架就可以使用它——但如果它有所帮助，那就是它的形状。
> **许可证：** 本项目在Hippocratic License 3.0下**源代码可用** —— *不是* OSI “开源”。请参阅 `LICENSE`。
## 三层
- **过程** — `Encounter`（一次工作会话）通过 `NEXT_ENCOUNTER` 链接。代理自己的内存排序。仅由受保护的 `advance_encounter` / `close_encounter`写入——主干保持为单个干净的链。
- **语义** — `Observation` / `Question` / `Hypothesis` / `Concept` / `Note`。代理已经理解的内容：观察、开放线程、工作解释、综合。
- **引用** — `Component`（指向来源的书签：`source_kind` + `source_label` + `source_key`）和 `Citation`（出处：`kind`、`uri`/`query`、`snapshot`）。代理注解其来源；它从不复制它们。
## 工具表面
- **会话：** `advance_encounter`（打开会话，返回重新进入的有效载荷——最近的会话、开放问题、活跃的假设、最近的概念），`close_encounter`（在会话结束时注解）。
- **写入：** `create_entities`（自动锚定到开放会话），`create_relations`（代理作者的链接），`delete_entities`，`delete_relations`。
- **读取：** `search`，`find_by_name`，`read_cypher`（EXPLAIN-gated，只读），`get_schema`，`list_node_types`，`list_relation_types`，`list_vocabulary`。
- **分析（GDS）：** `gds_create_projection` → `gds_pagerank` / `gds_betweenness` / `gds_louvain` / `gds_wcc` → `gds_drop_projection`。
操作手册作为MCP资源 `agent-memory://howto` 提供，也可以在 `src/mcp_agent_memory/HOWTO.xml` 处找到——在记录之前请先阅读它。
## 快速开始
```bash
uv sync
uv run mcp-agent-memory --db-url bolt://localhost:7687
```
## Docker 栈（自包含单元）
`compose.yml` 将 Neo4j **和** 服务器一起启动：
```bash
cp .env.example .env # 设置一个强 NEO4J_AGENT_MEMORY_PASSWORD
docker compose up --build # 流式 HTTP 在 :8003
```
带有 APOC 和图数据科学的 Neo4j 社区版自动安装；查询级别的健康检查控制启动，因此服务器永远不会与未准备好的数据库竞争；社区版允许一个用户数据库，因此堆栈通过 `initial.dbms.default_database` 命名它。
## 配置
CLI 参数 → 环境变量 → 默认值：`NEO4J_URL`，`NEO4J_USERNAME`，`NEO4J_PASSWORD`，`NEO4J_DATABASE`，`NEO4J_TRANSPORT`（`stdio` | `streamable-http` | `sse`），`NEO4J_MCP_SERVER_*`，`NEO4J_NAMESPACE`，`NEO4J_READ_TIMEOUT`，`NEO4J_MCP_STATELESS_HTTP`（默认为 `true`；为需要 `Mcp-Session-Id` + `DELETE`拆除的会话桥接客户端设置 `false`）。
单租户：一个代理，一个内存图，一个 Neo4j 数据库。
