内容
# Pseudolife-MCP
<!-- mcp-name: io.github.Pseudogiant-xr/pseudolife-mcp -->
[](https://pypi.org/project/pseudolife-mcp/)
[](https://github.com/Pseudogiant-xr/Pseudolife-MCP/actions/workflows/ci.yml)
[](LICENSE)
[](https://pypi.org/project/pseudolife-mcp/)
**为 Claude Code 提供持久的长期记忆，基于模型上下文协议。**
一个 MCP 服务器，为 Claude（或任何支持 MCP 的客户端）提供长期记忆，该记忆在会话之间持久存在 — 生存于上下文压缩和 `/clear` 重置。Claude 是大型语言模型；这个服务器是它在磁盘上的记忆。
你将获得：
- **类似记忆的联想记忆** — 一个 8 频段的近期连续统，从 `working` 到 `forever`，按余弦相似度排名，具有矛盾检测和取代。
- **规范事实，而不是印象** — 每个 `entity.attribute` 槽有一个 *当前* 值；修正会取代而不是静默覆盖，全版本历史存活。
- **梦境** — 一个捆绑的提取器（或通过 Max 计划的 Claude Sonnet）将记忆流凝聚成事实和知识图谱，而你不注意时。
- **从自身工作中汲取教训** — 成功、死胡同和修正成为指导，在每个会话开始时显示。
- **一个网页控制台来观察它的思考** — 上面的 Cortex 控制台，加上引用的世界事实、会话剧集和文档 RAG。
## 快速入门
需要 Docker 和 Claude Code。从克隆到第一个记忆，只需一个命令：
```bash
git clone https://github.com/Pseudogiant-xr/Pseudolife-MCP.git
cd Pseudolife-MCP
ops/install.sh # Linux / macOS
ops\install.ps1 # Windows (pwsh 7+)
```
安装程序运行预飞行检查（每个缺少的先决条件有一行确切的修复），询问应该巩固记忆的 **梦境提取器** —
- **仅 Sonnet** — 最轻的安装：通过 CLI 垫片的 Claude Sonnet（需要登录的 Max 计划 `claude` CLI）；侧边栏镜像 **从不构建或拉取**（~9 GB 更轻；梦境在垫片关闭时暂停）；
- **Sonnet 备用** — Sonnet 主要，捆绑的侧边栏作为自动备用（Max 计划 CLI 加 ~9 GB 镜像）；
- **侧边栏** — 捆绑的本地 CPU 模型；不需要 Claude 计划，适用于所有人（~9 GB 镜像）—
然后启动堆栈，安装会话钩子，提供将内存循环块追加到 `~/.claude/CLAUDE.md`（循环实际触发所需），运行 `claude mcp add`，并进行守护进程健康检查。幂等 — 随时重新运行；`--extractor <mode>` 切换提取器设置，`ops/install.sh --extractor sonnet-only --claude-md append` 非交互式运行。Linux（Docker 引擎）：您的用户必须位于 `docker` 组中 — `sudo usermod -aG docker $USER`，然后注销/登录（预飞行检查）。
<details>
<summary>手动安装（安装程序自动执行的步骤）</summary>
```bash
ops/preflight.sh # 或 ops\preflight.ps1 — 检查 docker/git/claude，打印任何缺失的精确修复
docker volume create pseudolife-mcp-bank
docker volume create pseudolife-mcp-state
docker compose -f ops/docker-compose.yml up -d --build # 首次构建，一次
# 验证，然后连接到 Claude Code：
curl http://127.0.0.1:8765/health
claude mcp add --transport http --scope user pseudolife-memory http://127.0.0.1:8765/mcp
# 教会 Claude 记忆循环 — 必需，不可选：没有固定的指令，工具将保持未使用。 将捆绑的块追加到您的全局 CLAUDE.md（适用于每个项目）：
cat examples/CLAUDE.memory.md >> ~/.claude/CLAUDE.md
# （PowerShell：Add-Content "$env:USERPROFILE\.claude\CLAUDE.md" (Get-Content examples\CLAUDE.memory.md -Raw））
```
可选旋钮位于 `ops/.env`（`cp ops/.env.example ops/.env` — 安装/更新脚本也将其搭建；每个值都被注释，缺少的文件完全按默认值运行）。
</details>
然后在任何 Claude Code 会话中： *"记住我的登台框是 haze-02"* → Claude 调用 `memory_store`；在下一个会话中， *"哪个框是登台？"* → `memory_search` 找到它。在 Cortex 控制台中浏览所有内容： <http://127.0.0.1:8765/ui/>。
## 这是什么
一个通过 MCP 暴露的记忆引擎。没有聊天界面，也没有进行思考的 LLM — Claude 是智能；这些是它调用的存储和回忆重要内容的工具。（模型 *作为管道* 被捆绑：用于检索的嵌入权重和可选的 CPU 提取器侧边栏，它在您睡眠时将记忆凝聚成事实。）
它分层了几个互补的存储：**联想连续统**（一个 8 层近期分层嵌入存储，从 `working` 到 `forever`，按余弦相似度排名，具有新颖性门控存储、矛盾检测和取代）；**皮质**（槽键控规范事实 — 每个 `entity.attribute` 一个 *当前* 值，具有出处层和竞争者停车场，而不是静默覆盖）；一个带有封闭关系词汇和读取推断的键入 **知识图谱**；**世界皮质**（关于外部现实的 *引用* 事实，按新鲜度类别进行年龄衰减信任）；**程序经验** 从代理自己的工作中学习；和一个 ChromaDB **引用库** 用于文档 RAG。规范层深入：[记忆模型](docs/guide/memory-model.md)；图谱和多跳回忆：[检索](docs/guide/retrieval.md)。
状态存活在 Postgres（持久的真相来源）后面，通过单个长期守护进程；每个会话都通过 HTTP（或对于主机进程安装，一个薄的 stdio 垫片）附加到它。结果：Claude 可以继续它离开的地方，在事实改变时纠正自己，并在关系上进行推理 — 而无需您重新解释上下文每个会话。
## 文档
本 README 是入口 — 安装、连接和基本循环。深入的材料存在于用户指南中：
| 页面 | 内容 |
|---|---|
| [配置](docs/guide/configuration.md) | 环境变量、调整的默认值、工具集层、stdio 垫片、LAN 共享、数据布局、备份、模式历史 |
| [检索](docs/guide/retrieval.md) | 重新排序器、BM25 混合、弃用底线、排名跟踪调试、`memory_recall`、知识图谱 |
| [梦境](docs/guide/dreaming.md) | 提取器层、捆绑的侧边栏、升级提取器、Sonnet 备用、节奏、深度梦境、凝聚 |
| [剧集和会话](docs/guide/episodes.md) | 守护进程拥有的会话剧集、简报钩子、嵌套子剧集、标签 |
| [记忆模型](docs/guide/memory-model.md) | 皮质槽、出处竞争者、世界皮质、经验教训、时间/HLC 时间戳 |
| [基准](docs/guide/benchmarks.md) | LongMemEval 结果；为什么提取质量占主导地位 |
加上 [`evals/README.md`](evals/README.md)（完整的基准测试方法）和 [CONTRIBUTING](CONTRIBUTING.md)。
## 暴露的工具
表面在 2026-07-02 合并（55 → 32 个工具；现在 33 个带有 `memory_toolset`）：生命周期家族成为动词分派工具（`memory_dream`、`memory_forget`、`memory_graph_review`），而转储/内省视图移动到 Cortex 控制台（REST）— 清单是每个会话的代理上下文，因此保持精简。
| 工具 | 目的 |
|------|---------|
| `memory_store(text, source?, tags?, origin?)` | 记住一个持久的事实 / 决定 / 观察（规范事实通过梦境传递或 `memory_fact_set` 到达皮质） |
| `memory_search(query, top_k?, filters..., rerank?, bm25?, explain?, verbose?)` | 联想检索；规范 `皮质` 事实在回忆命中之前出现；`explain=True` 附加排名跟踪 |
| `memory_recent(n?, sources?, episodes?, tags?, verbose?)` | 最新存储，按时间戳排序（调试 + 会话跟进） |
| `memory_supersede(old_text, new_text)` | 显式修正 — 标记记忆过时，保持其作为历史 |
| `memory_forget(scope, ...)` | 从一个存储中硬删除：`memory`（按文本/子字符串/源/剧集/标签）、`fact`、`world` 或 `lesson`（按实体/属性） |
| `memory_stats()` | 每频段大小、命中率、总数 |
| `memory_get(entry_id)` / `memory_reinforce(entry_id)` | 取消引用记忆 ID 到其完整剧集（+ `consolidated_into`）；在发现它有用后强化它 |
| `memory_fact_get(entity, attribute)` | 槽位的当前规范值（+ 公园竞争者）；在空槽位上返回排名的 `candidates`（相同实体，然后是类似槽位） |
| `memory_fact_set(entity, attribute, value, origin?, confidence?)` | 故意断言规范事实（插入 / 确认 / 取代 / 争议） |
| `memory_fact_resolve(entity, attribute, accept)` | 解决争议的槽位 — 采用 (`true`) 或丢弃 (`false`) 竞争者 |
| `memory_history(entity, attribute?)` | 使用 `attribute`：槽位的版本时间线，具有写入者/时间戳。使用时：实体的因果链 — 有日期的事实/条目/边缘/经验事件（“是什么导致 X”） |
| `memory_world_set(entity, attribute, value, source_url?, ...)` | 断言引用的世界事实（外部知识；按新鲜度类别的年龄衰减信任） |
| `memory_world_search(query, top_k?, verbose?)` | 搜索世界事实 — 每个都带有 `effective_confidence`、`stale` 标志和其引用 |
| `memory_outcome(task, outcome, about?, detail?, polarity?)` | 记录程序结果信号（`success`/`failure`/`correction`）；梦境将信号提炼成经验教训 |
| `memory_lesson_search(query, top_k?, verbose?)` | 回忆针对当前任务的已学习经验教训 — 注意 `polarity` `-` 死胡同；`re_verify` 标志在主题事实自上次更改后重新验证的经验教训 |
| `memory_dream(action, limit?, cursor?, apply?, snippets?)` | 驱动梦境：`status` / `pull` / `commit` / `run`（服务器端提取器）/ `deep`（完整语料库图谱凝聚；除非 `apply`，否则为干运行，它首先快照图谱表；`snippets=false` 省略候选证据；响应带有丰富证据的 `merge_proposals`，用于近似重复三元组） |
| `memory_graph_review(action, proposal_id?, proposals?, scope?, src?, dst?)` | 处理审查队列：`list` / `propose` / `dismiss_pair` / `accept_link` / `reject_link` / `accept_merge` / `accept_junk` / `reject_entity`（合并/实体决策被审计戳记为 `decided_by=agent` 通过 MCP，`human` 通过控制台） |
| `memory_session_title(title)` | 命名此会话的自动打开的剧集（默认标题是通用的） |
| `memory_episode_start(title, hint?)` / `memory_episode_end()` | 打开/关闭一个用于重大任务的嵌套子剧集；打开的条目存储在其 ID 下 |
| `memory_episode_summary(id)` | 统计 + 标签/源分布 + 剧集内的最新条目 |
| `memory_consolidation_candidates(query?, episode?, ...)` | 聚类近似重复的记忆，准备合并 |
| `memory_consolidate(replaces, new_text, source?, tags?)` | 原子取代 + 存储 — 用一个规范笔记取代一个集群 |
| `memory_graph_relate(src, relation, dst, ...)` | 断言键入边（封闭关系词汇；重新断言增加置信度） |
| `memory_graph_unrelate(src, relation, dst)` | 撤销边（取代，保留审计） |
| `memory_alias(entity, alias)` | 绑定替代名称 — 查找首先解析别名 |
| `memory_graph(entity, depth?, include_facts?, to?, relation_filter?)` | 具有派生传递/逆边缘和每个边缘的 `EXTRACTED/INFERRED/AMBIGUOUS` 出处标签的实体邻域（≤3 跳） |
| `memory_recall(query, hops?, top_k?, verbose?)` | 用于关系问题的多跳检索；`low_confidence: true` → 回退到 `memory_search` |
| `memory_relation_define(name, description, ...)` | 增长封闭关系词汇（故意，罕见行为） |
| `document_ingest(path, source?)` | 在引用库中索引文件（txt/md/pdf） |
| `document_search(query, top_k?)` | 仅在引用库上进行 RAG 搜索 |
| `memory_toolset(action)` | 检查或更改此会话的可见性层：`status` / `expand` / `collapse` |
每个工具都返回纯 JSON。参见 `pseudolife_memory/mcp_server.py` 中的文档字符串 — 这些是 Claude 读取的内容，以决定何时调用哪个工具。五个回忆路径工具默认返回 **紧凑条目**（结果有效载荷是每个检索的代理上下文）；传递 `verbose=true` 以获取完整元数据。完整表格转储和拓扑视图存在于 **Cortex 控制台**（`/api/*`）和 `pseudolife-mcp 简报` CLI 中。
**工具集层。** 三个可见性层 — `minimal`（7 个工具）、`core`（20 个，默认发货）、`full`（33 个）— 按会话过滤在 `tools/list`；会话使用 `memory_toolset` 将其自己的层级提升或降低，然后调用隐藏的工具。默认值、每个客户端映射和弱模型部署：[配置 — 工具集层](docs/guide/configuration.md#toolset-tiers)。
## 架构
一个 **记忆守护进程** 拥有银行并通过流式 HTTP 在 `/mcp` 上提供 MCP 服务；每个 Claude Code 会话（和任何 LAN 代理）都连接到它。**Postgres 16 + pgvector**（在 Docker 中）是持久的真相来源 — 内存 MIRAS 波段是一个写入缓存，在启动时进行水合（一个小的 `weights.pt` 仅保留波段计数器 — 没有 MLP 权重）。
守护进程运行 **或者** 容器化（推荐 — 便携，无主机 Python）**或者**作为主机进程。Claude Code 通过 **或者** HTTP（推荐）**或者**通过薄的无火炬 stdio **垫片** 连接到守护进程：
```
Claude 会话 A ─┐ HTTP（推荐）
Claude 会话 B ─┼───────────────────► pseudolife-mcp 守护进程 ─► Postgres（Docker）
LAN 代理 ────────┘ 或 stdio 垫片 （单个写入器） pgvector
（每个会话） 主进程 或 Docker
```
这通过构造解决了两个 v0.1 危险：单个写入器意味着并发会话不会相互覆盖，并且条目是事务性的，因此崩溃不会清除银行。在关联波段之上，规范层 — 皮质、世界事实、经验教训、时间/高级别时间戳记（[记忆模型](docs/guide/memory-model.md)）— 加入到键入的知识图谱，可以通过 `memory_graph` 和多跳 `memory_recall` 进行遍历。
## 安装 — 容器化（推荐，任意操作系统）
整个堆栈 — Postgres **和** 记忆守护进程 — 在 Docker 中运行。无需主机 Python，无需火炬安装，无需版本偏差；守护进程镜像包含 CPU 仅限的火炬和 `all-MiniLM-L6-v2` 权重，因此它在 Windows / macOS / Linux 上运行相同。仅需 Docker；构建一次：~3 GB 守护进程镜像 + ~0.6 GB Postgres + ~9 GB 提取器侧边栏（跳过侧边栏的安装程序的 `sonnet-only` 模式）。
```bash
git clone https://github.com/Pseudogiant-xr/Pseudolife-MCP.git
cd Pseudolife-MCP
# 1. 一次性：创建两个持久卷（银行 + 守护进程状态）。
docker volume create pseudolife-mcp-bank
docker volume create pseudolife-mcp-state
# 2. 构建 + 启动所有三个服务（Postgres，提取器，然后是守护进程）。
docker compose -f ops/docker-compose.yml up -d --build
```
> **从预重命名安装升级**（卷 `ops_pseudolife_pgdata` / `ops_pseudolife_data`）？不要重命名这些卷 — 通过创建 `ops/.env` 保留对它们的引用，并添加 `PSEUDOLIFE_BANK_VOLUME=ops_pseudolife_pgdata` 和 `PSEUDOLIFE_STATE_VOLUME=ops_pseudolife_data`，然后执行 `up`。参见 docker-compose 文件头。
> **Windows:** Docker Desktop 的 WSL2 虚拟机默认占用高达 ~50% 的主机 RAM；堆栈在默认侧边栏（~1 GB 在 `sonnet-only` 模式下）下需要 ~6–7 GB 内存 — 通过 `ops/wslconfig.example` （参见[故障排除](#troubleshooting)）限制 VM。
守护进程在 `http://127.0.0.1:8765/mcp` 上提供 MCP 服务，并随 Docker 重启 — 无需登录任务。首次构建下载模型到镜像（一次）；之后的每个容器启动都是离线的且快速的。将 Claude Code 通过 **HTTP** 连接到这里（如下）。数据实际存储位置，以及如何备份：[配置 — 数据布局](docs/guide/configuration.md#data-layout)。
**主机进程安装（Windows，用于 GPU / 开发）：** 在 Docker 中运行 Postgres，但在主机 Python 上运行守护进程 — 用于开发守护进程或在本地 GPU 上运行嵌入器的操作。步骤、 `pseudolife-mcp` CLI 模式和登录自动启动任务：[配置 — 主机进程安装（Windows，用于 GPU / 开发）](docs/guide/configuration.md#host-process-install-windows-for-gpu--dev).
## 更新
在 `git pull`（或本地代码更改）后，**仅需重新部署守护进程** — 安全地，无需触及 Postgres 或提取器：
```powershell
.\ops\update.ps1 # Windows
```
```bash
./ops/update.sh # Linux / macOS
```
它备份银行（`pg_dump` + 状态卷 tarball），标记回滚镜像，仅需重新创建 **守护进程**，并等待 `/health`。它从不运行 `down -v`。（主机进程安装：只需重启守护进程 — `pip install -e .` 是可编辑的。）然后回收累积的构建缓存：`docker builder prune`（安全 — 它只触及构建层）；从不 `docker system prune --volumes`，它会删除卷。
有时可以回收累积的构建缓存：`docker builder prune`（安全 — 它只影响构建层）；绝不 `docker system prune --volumes`，它会删除卷。
## 接入 Claude 代码
### 插件（最简单的方式）
在运行守护进程后，Claude 代码中有两个命令可以连接所有内容 - MCP 服务器、会话开始简介钩子、内存循环指令以及 `/dream` 和 `/memory-status` 命令：
```bash
/plugin marketplace add Pseudogiant-xr/Pseudolife-MCP
/plugin install pseudolife-memory@pseudolife-mcp
```
该插件取代了手动的 `claude mcp add`、settings.json 钩子和下面的 CLAUDE.md 模块 - 相同的固定指令作为会话上下文从守护进程接收。详细信息、非默认端口/令牌和手动连接迁移：[插件/README.md](plugin/README.md)。
### HTTP 传输（手动等效）
守护进程已经通过 HTTP 提供 MCP 服务，因此可以直接将 Claude 代码指向它 - 无需 shim、无主机命令，也无需特定于操作系统的操作。只需一个命令：
```bash
claude mcp add --transport http --scope user pseudolife-memory http://127.0.0.1:8765/mcp
```
（ `--scope user` 将其注册到每个项目中；如果只为当前项目注册，请删除它。）或者，您可以自己编写等效的 JSON - 进入顶级 `mcpServers` 键下的 `~/.claude.json` 以适用于用户范围，或进入项目根目录下的 `.mcp.json` 以适用于项目范围：
```json
{
"mcpServers": {
"pseudolife-memory": {
"type": "http",
"url": "http://127.0.0.1:8765/mcp"
}
}
}
```
如果您使用 `PSEUDOLIFE_MCP_TOKEN` 运行守护进程，请添加一个 `headers` 键：`"headers": { "Authorization": "Bearer <your-token>" }`。
### 验证
运行 `claude mcp list`（服务器应报告 ✓ connected），然后让 Claude 存储一个记忆，证明此安装有效，并检查它是否出现在 Console 的 Stream 标签页中，网址为 <http://127.0.0.1:8765/ui/>。
## 推荐的代理设置（CLAUDE.md）
服务器的值完全取决于代理 *使用*它的好坏 - **此步骤使记忆循环实际触发**；跳过此步骤的安装将得到一个健康的守护进程，但其工具永远不会被调用。**插件用户跳过此部分**：插件的 SessionStart 钩子在每个会话中都会注入相同的模块。其他人将循环编码为固定指令：将其追加到全局 `~/.claude/CLAUDE.md`（适用于每个项目）或项目特定的 `CLAUDE.md` / `AGENTS.md`：
```bash
cat examples/CLAUDE.memory.md >> ~/.claude/CLAUDE.md
# PowerShell: Add-Content "$env:USERPROFILE\.claude\CLAUDE.md" (Get-Content examples\CLAUDE.memory.md -Raw)
```
该模块（[`examples/CLAUDE.memory.md`](examples/CLAUDE.memory.md)）教导循环：**在开始时回忆**（`memory_search` / `memory_lesson_search` / `memory_fact_get` / `memory_world_search`），**边走边捕捉**（`memory_store`，带有诚实的 `origin`，`memory_fact_set` 用于规范事实，`memory_world_set` 用于引用的外部事实，`source="status"` 用于详细日志，以便它们不进入梦境），**在结束时反思**（`memory_outcome` - 梦境将这些信号提炼成在下一个会话开始时浮现的课程）。
一个命令 - `ops\install-hook.ps1`（Windows，PowerShell 7）或 `ops/install-hook.sh`（Linux/macOS）- 安装 **SessionStart 简介钩子**（您的记忆不确定的内容 + 过去工作的课程 + 验证的世界事实 + 我们离开的地方，在每个会话开始时注入）。它备份您的 `settings.json` 并具有幂等性。手动钩子 JSON、简介预算标志以及会话剧集如何打开/关闭/恢复，无需任何钩子：[剧集和会话](docs/guide/episodes.md)。
## 使用模式
### 会话开始
加载您之前处理过的内容，在压缩过程中持久存在：
```bash
memory_search("项目 X 的上下文")
```
### 工作中
存储真正的决策；跳过短暂的聊天（已发货的存储网关是宽容的，因此只有刻意和持久的主张）：
```bash
memory_store("决定使用_stdio传输MCP，因为没有端口冲突", source="pseudolife")
```
### 被纠正时
标记旧事实已取代 *和* 存储纠正；两者都在未来的检索中浮现，新的排名更高：
```bash
memory_supersede(
"提供者接口使用同步调用",
"提供者接口使用异步调用 - 同步版本仅是v0.7原型"
)
```
### 清洁
硬删除（至少需要一个过滤器用于 `memory` 范围，防止意外的大规模删除）；要“保留历史记录但标记为错误”，请改用 `memory_supersede`：
```bash
memory_forget(scope="memory", source="test-noise")
memory_forget(scope="fact", entity="test-entity")
```
### 发现银行中有什么
打开 Cortex 控制台 - 源、标签、剧集和全表视图都在那里。 更深入：[重排序、BM25、放弃和跟踪调试](docs/guide/retrieval.md) · [剧集 + 标签](docs/guide/episodes.md#episodes--tags) · [规范事实、对手、世界事实、课程](docs/guide/memory-model.md) · [巩固工作流（代理驱动的重复数据删除）](docs/guide/dreaming.md#consolidation-workflow-agent-driven-dedup).
## 梦境 - 将记忆巩固为事实
一个 **梦境** 在您不注意时，将最近的联想流提炼成规范的皮层事实：拉取未巩固的记忆 → 提取 `(entity, attribute, value)` → 推进一个光标，以便没有任何内容被重新处理。提取是可插拔的：
| 层级 | 运行方式 | 需要 | 质量 |
|------|-------------|-------|---------|
| **0 — 基线** | `memory_dream(action="run")`（正则表达式层）— 无头、本地、免费 | 无 | 弱 |
| **1 — 代理驱动** | **代理本身** 是网关：`/dream` 命令 | 您已经运行的代理 | 最高 |
| **2 — 默认出货** | 守护进程自动扫描 → 捆绑的CPU边车，或任何OpenAI兼容的端点 | 无（边车） | 高；如果本地则免费 |
该堆栈预配置了第2层（定制的Gemma 4 E4B提取器微调，位于llama.cpp边车中，内部使用）。扫描节奏、将梦境指向更大的本地模型或Claude Sonnet，并带有自动边车故障转移、完整语料库**深度梦境**图传递和隐私/成本权衡：[梦境](docs/guide/dreaming.md)。
## 基准测试
在知识更新子集上 [LongMemEval](https://arxiv.org/abs/2410.10813) （预言变体，本地上限提取器），巩固的事实姿态比朴素RAG高9个点，同时读取约40%的上下文：
| 臂 | 准确性 | 上下文令牌/问题 |
|-----|----------|------------------------|
| 朴素RAG（前6个回合） | 0.615 | 1638 |
| 仅皮层事实 | 0.564 | **59** |
| **混合（事实+前3个回合）** | **0.705** | 979 |
事实脊柱本身提供了RAG在 **3.6%的令牌预算**上的92%的准确率。设置、注意事项以及提取质量是主要因素：[基准测试](docs/guide/benchmarks.md)；完整方法论：[`evals/README.md`](evals/README.md).
## Cortex 控制台（Web UI）
一个操作员仪表盘，由守护进程本身提供服务 - 将浏览器指向 **`http://127.0.0.1:8765/ui/`** （`/health` 和 `/mcp` 端点保持不变；控制台是附加的）。这是一个只读仪表盘，用于查看和控制人类无法观察的记忆：**观测站**（健康状况、每层计数、8频带连续统、梦境仪表）、**皮层**（规范事实，具有出处、版本历史时间线和内联接受/拒绝争议槽）、**世界/课程/剧集**、**流**（实时搜索，带有重排序/BM25切换和排名跟踪调试器）、**图表**（交互式力导向可视化器）和 **控制台**（每个安全的 `config.yaml` 标量，具有实时和重启徽章、差异预览和原子保存）。
### 认证
`/ui`（静态壳）和 `/health` 是开放的；`/api/*` 需要与设置的 `PSEUDOLIFE_MCP_TOKEN` 相同的 bearer。控制台提示并本地存储令牌。 无需构建步骤，无需 CDN，完全离线 - 香草 ES 模块 + 供应商 OFL 字体直接从守护进程提供服务。
## 功能一览
| 功能 | 状态 |
|---|---|
| 传输 | 可流式传输的 HTTP MCP 守护进程 (`/mcp`)；主机进程安装的可选 stdio shim |
| 存储 | Postgres 16 + pgvector（真实来源）； ChromaDB 用于参考库 |
| 联想连续统 | 8 层余弦 MIRAS 波段，新型存储门控，矛盾检测，取代 |
| 规范事实皮层 | 单一写入者：LLM 梦境传递 + `memory_fact_*` （正则自动提升，默认关闭） |
| 来源竞争者 | 层级排名守护 `user > action > agent`；`memory_fact_resolve` |
| 知识图 | 类型实体/边，封闭关系词汇，读取关闭（Postgres + NetworkX，无 AGE/Cypher） |
| 世界皮层 | `memory_world_*` — 引用外部事实 + 年龄衰减新鲜度（手动摄入） |
| 程序记忆 | `memory_outcome`（信号）→ 梦境合成课程 via `memory_lesson_search`；`prefers`/`avoids` 图形边；单一写入者 |
| 时间感 + 多写入者 | 每写入时间戳（tx/有效时间，HLC排序，写入者/会话）；`memory_history`；读取相对 `age`；写入模式缝隙（快照实时，occ 第2阶段） |
| 剧集 + 标签 | 会话剧集守护进程拥有，按稳定会话ID键控；延迟打开 + 空闲回收 + 清空空剧集；带有子树展开召回的嵌套子剧集；多值 `tags=[...]` |
| 会话简介 | SessionStart 钩子注入不确定图 + 课程 + 验证的世界事实 + 上次会话回顾 (`pseudolife-mcp 简介`) |
| 整合 | `memory_consolidation_candidates` + `memory_consolidate` |
| 可选组件 | 交叉编码器重排序器 (`rerank=True`, ~80 MB)；BM25 混合池 (`bm25=True`, 标准库仅限)；ONNX 嵌入后端 (`pip install .[onnx]` — ~3 倍更快的 CPU 编码，位身份，自动启用安装时)；NLI 矛盾评分器 (`pip install .[nli]`，~278 MB) |
| Web 控制台 | Cortex 控制台在 `/ui/` — 健康/统计，事实审查 + 历史，图表可视化器，搜索/跟踪，配置编辑器（只读，令牌控制像 `/mcp`） |
| 模式版本 | v22（Postgres 元版本）— 添加 `ADD COLUMN IF NOT EXISTS` 迁移在守护进程启动时；遗留文件模式 `.pt` 银行自动迁移到 Postgres；[完整版本历史](docs/guide/configuration.md#schema-version-history) |
## 故障排除
首先运行 `curl http://127.0.0.1:8765/health` — 它报告模式版本、存储后端、身份验证状态和 `persist_errors`（非零表示写入失败到达 Postgres；检查 `docker logs pseudolife-mcp-daemon`）。
- **第一次构建很慢/很大。** 守护进程镜像包含 CPU 火炬和嵌入模型（~3 GB，几分钟；提取器边车添加了 ~5.3 GB 模型下载）。之后每次启动都是离线的和快速的 - 如果 *重建* 正在重新下载模型，则 Docker 层缓存已被修剪。
- **WSL2 上的 Docker 占用 RAM** （Windows）：WSL2 虚拟机（`Vmmem`）默认占用高达 ~50% 的主机内存。复制 `ops/wslconfig.example` 到 `%USERPROFILE%\.wslconfig`，调整 `memory=`，然后 `wsl --shutdown`。
- **端口已被占用**：堆栈绑定 `127.0.0.1:8765`（守护进程）和 `127.0.0.1:5433`（Postgres）。如果其中一个冲突，请更改 `ops/docker-compose.yml` 中的主机端。
- **控制台显示“离线”/未经授权**：“离线”表示守护进程无法访问（参见上文）；401 提示表示它运行的是 `PSEUDOLIFE_MCP_TOKEN` — 将该令牌粘贴到控制台的令牌对话框中。
- **Claude Code 看不到工具**：`claude mcp list` 应该显示 `pseudolife-memory` ✓ 已连接。如果不是，请重新检查 URL (`http://127.0.0.1:8765/mcp` — `/mcp` 路径很重要）和设置令牌时的 bearer 头。
## 卸载
每次删除操作都是故意的：
```bash
# 1. 可选：首先进行最终备份（ops/backup.ps1 或 ops/backup.sh）。
# 2. 停止并移除容器（卷存活）。
docker compose -f ops/docker-compose.yml down
# 3. 移除 MCP 注册。
claude mcp remove pseudolife-memory
# 4. 仅当确定时：删除数据卷（这是内存）。
docker volume rm pseudolife-mcp-bank pseudolife-mcp-state
```
主机进程安装：还需注销登录任务（`Unregister-ScheduledTask -TaskName "Pseudolife-MCP Daemon"`）并从 `~/.claude/settings.json` 中移除 SessionStart 简介钩子（一个带有时间戳的 `.bak-*` 文件位于其旁边）。
## 测试
`pip install -e .[dev]`，然后 `pytest tests/`。测试套件涵盖了从 MemoryService 接口到 Cortex 控制台 REST API 的每一层；模型密集型部分被存根，因此保持快速和离线。PG 支持的套件针对一个临时 `pseudolife_memory_test` 数据库在捆绑的开发容器上运行（而非您的真实银行），并在没有 Postgres 的情况下干净地跳过。完整的开发设置：[CONTRIBUTING](CONTRIBUTING.md)。
## 尚未构建的内容
- **通过 MCP 采样进行反思** — 将允许梦境借用 *Claude 本身* 作为提取器； [Claude Code 尚不支持](https://github.com/anthropics/claude-code/issues/1785)。
- **跨机器同步** — 内存存储在一台 PC 的磁盘上；使用 rclone / syncthing 进行同步作为练习。
- **自动世界知识摄入** — 从实时网络填充世界皮层需要一个网页获取工具，独立服务器不提供；具有 Web 访问权限的代理可以今天通过 `memory_world_set` 自动执行获取 + 引用步骤。
## 许可证
Apache-2.0 — 参见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器