Pseudolife Memory

Pseudolife-MCP

简体中文 · 日本語 · 한국어 · Português (BR) · Español

为 Claude Code、Codex 和其他 MCP 客户端提供持久的长期记忆。

一款 MCP 服务，为编码 Agent 提供可跨会话持久保存的长期记忆——即使上下文经过压缩或开始全新任务，记忆也不会消失。编码 Agent 负责智能；此服务则将记忆保存在磁盘上。

你将获得：

• 联想记忆，坦诚面对遗忘 — 一个扁平的相似度存储，按稠密与词汇混合检索结果排序，并通过冲突检测允许潜在更新，同时保留早期来源笔记；整条笔记的替换则需要明确操作。（实测结论：一项预注册的消融测试发现，先前的 8 段连续结构在所有评估门槛上都与扁平存储不相上下，因此采用了更简单的结构；只需一行配置即可启用连续结构。）
• 规范事实，而非凭感觉 — 每个 entity.attribute 槽位只保留一个 当前 值（或对于可同时容纳多个值的槽位，保留一个成员集合）；更正会取代旧值，而不是悄然覆盖，完整版本历史也会保留。
• Dreams — 使用捆绑的本地提取器，或任意兼容 OpenAI 的端点（Max 套餐中的 Claude 模型、ChatGPT 套餐中的 GPT-5.6 模型、LM Studio、Ollama、vLLM），在你不留意时将记忆流整理为事实和知识图谱。
• 从自身工作中吸取经验 — 成功经验、死胡同和你的更正会转化为应做/避免的指导，并在每次会话开始时呈现。
• 通过 Web 控制台观察思考过程 — 上方的 Cortex Console，以及带引用的世界事实、会话事件和文档 RAG。

有实测数据，有据可查——完整的 500 题 LongMemEval 测试涵盖全部六种问题类型，每个数字都附有已提交的运行产物：

**2026-08-25 起弃用（#188）：知识更新得分 0.936 的宣传结论。**该数据是在 2026-07-30 的基准测试堆栈（Qwen3.6-27B 答题模型和评审器）上测得的。2026-08-17 迁移到 Qwen3.8-27B 后，对相同的 78 个问题重新测试，级联方案得分为 0.846，低于朴素 RAG 对照组——后者在两个堆栈上的得分均为 0.859。级联方案会采用事实主干给出的答案，除非该通道表示“我不知道”，因此它衡量的不仅是记忆能力，也同样受答题模型的弃答行为影响：旧堆栈中弃答 32/78，提交答案的准确率为 46/46；新堆栈中弃答 22/78，准确率为 0.839。上方 500 个问题的表格使用的是较旧的评审器，尚未重新评审，因此其中级联方案一行应视为上限。

完整表格、按类型划分的细分结果、两个堆栈的并列对比以及所有产物，见：基准测试。

快速开始

安装并注册精简版。无需 Docker、无需设置数据库，也无需容器运行时：

pip install "pseudolife-mcp[lite]"
claude mcp add --scope user pseudolife-memory -- pseudolife-mcp

使用 Codex 而非 Claude Code——配置形式相同：

pip install "pseudolife-mcp[lite]"
codex mcp add pseudolife-memory --env PSEUDOLIFE_WRITER_ID=codex -- pseudolife-mcp

对于 Codex，请先完成设置，再开始新任务。在 ~/.codex/config.toml 中现有的 [mcp_servers.pseudolife-memory] 表内，添加 startup_timeout_sec = 240、tool_timeout_sec = 240 和 required = true。对于尚未启动的守护进程，封装程序最长可能等待 180 秒；而 Codex 默认的启动等待时间为 10 秒。required 会在启动时显示记忆缺失的情况，并等待初始目录加载完成。这些只是建议的初始时限，并不保证首次模型下载能在时限内完成。工具时限为封装程序留出了 180 秒的截止时间，以便在宿主取消操作前报告失败；如有需要，可在终端中运行 pseudolife-mcp serve 预热。

在该表的工具配置中批准 memory_message（[mcp_servers.pseudolife-memory.tools.memory_message] approval_mode = "approve"，或允许一次并保留批准状态）；Codex 钩子设置（python ops/setup-codex-hooks.py）会在你批准钩子时设置此项，并保留你选择的任何值。默认情况下，Board 邮件可以唤醒处于闲置状态的 Codex 任务；被唤醒的任务会使用该工具读取邮件：若未批准该工具，任务就会停在提示词处，直到有人响应。在同一个 env 表中设置 PSEUDOLIFE_CODEX_DOORBELL = "0"，即可阻止任务被唤醒（参见 Codex 门铃）。 Agent 面板（会话间的对等感知与定向邮件）默认启用，并受 Bearer 身份验证保护。如果守护进程的 config.yaml 中没有 coordination.allowed_principals，则只允许单一的 PSEUDOLIFE_MCP_TOKEN 主体使用。来自 PSEUDOLIFE_MCP_TOKENS 映射的 Codex Bearer 会一直无法访问面板，除非操作员将其列出（allowed_principals: [default, codex]）。 在此之前，使用默认设置的 shim 会保持协调功能关闭，不会报错；使用 --enable 固定启用的 shim 则会显示附加不可用提示。 python ops/setup-codex-coordination.py --check 会报告 ready (default-on)，或指出原因。请参阅 Codex CLI 和桌面版。

MCP 握手会提供精简的回忆／捕获／反思说明。 如需完整的常驻指南，请将 捆绑的记忆区块复制到项目的 AGENTS.md 或 ~/.codex/AGENTS.md 中。有关会话简报和每轮提醒，请参阅 Codex 钩子与验证。 只使用一项 MCP 注册和一个钩子来源；已安装的插件可能已经提供其中一项。守护进程运行后，请在与已注册命令相同的环境中执行 pseudolife-mcp doctor。 它会检查握手和注释，不会调用银行工具。如果 shell 中没有 PSEUDOLIFE_MCP_TOKEN 或 PSEUDOLIFE_MCP_TOKEN_FILE，doctor 会从 Claude Code 注册项（~/.claude.json， 或 CLAUDE_CONFIG_DIR 指定的位置）获取令牌；否则会从 Codex 注册项获取，并在 credential_source 中注明来源；如果都没有，且守护进程要求令牌，则会报告 BearerMissing。

然后，在任一编码 Agent 中输入：“记住我的预发布环境主机是 haze-02” → Agent 会调用 memory_store；在下一个会话中输入 “预发布环境用的是哪台主机？” → memory_search 就能找到它。前往 Cortex Console 浏览所有内容： http://127.0.0.1:8765/ui/。

首次会话会自动启动守护进程，并在稳定的用户专属数据目录下配置内嵌式 PostgreSQL 18（通过 pg0-embedded，包含 pgvector），同时下载嵌入模型（约 1.2 GB，仅需一次）。 这是一个真正的 Postgres 数据库，而非精简版：pseudolife-mcp backup 会写入标准的无所有者 pg_dump 归档（以及一个状态归档，轮换保留 7 天），可恢复到任意 PostgreSQL 18 目标环境，不受角色限制——包括 Docker 层——因此从精简版扩容只需转储／恢复，而不是迁移项目（备份）。如需创建与层级和 Postgres 版本无关的副本，可使用 pseudolife-mcp export / import，以可移植的 JSONL 格式迁移整个数据库 （逻辑导出／导入）。 Windows 要求数据路径仅包含 ASCII 字符 （PSEUDOLIFE_MCP_DATA_DIR）。

lite 能为你提供什么，以及它唯一缺少的功能

差距，直白地说。 Lite 不附带提取器，因此 dream 流程仍会运行、修剪并确认其输入批次，但不会写入规范事实：在这条路径上，memory_fact_set 是唯一的 Cortex 写入工具。上面其他功能都能正常工作。这一情况不会被悄悄隐藏 — curl http://127.0.0.1:8765/health 会报告 "extractor": "none"，stdio shim 也会在会话开始时于 stderr 输出相同信息。

任何兼容 OpenAI 的端点都能弥补这一缺口。守护进程会继承启动时的环境，因此只需设置两个变量 — 以本地 Ollama 为例：

export PSEUDOLIFE_DREAM_BASE_URL=http://localhost:11434/v1
export PSEUDOLIFE_DREAM_MODEL=qwen2.5:7b
pseudolife-mcp serve

$env:PSEUDOLIFE_DREAM_BASE_URL = "http://localhost:11434/v1"
$env:PSEUDOLIFE_DREAM_MODEL    = "qwen2.5:7b"
pseudolife-mcp serve

随后 /health 会报告 "extractor": "configured"。有一点要注意：已经运行的守护进程会保留启动时的环境，而 shim 会重新连接到它，不会启动新进程 — 因此请先停止旧守护进程。托管端点也可用，但会失去零流出这一特性：记忆文本会离开这台机器。有关提取器层级、质量和权衡，请参阅：Dreaming。

Durable 层级 — Docker（推荐用于长期运行的记忆库）

包含以上所有功能，以及捆绑的提取器、外部卷、健康检查服务和备份/回滚工具。需要 Docker 和至少一个支持 MCP 的编码 Agent — Claude Code、Codex 和 Gemini CLI 均已完成端到端接入；其他工具则会获得可直接粘贴的配置（提供方矩阵）。从克隆到存入第一条记忆，只需一条命令：

git clone https://github.com/Pseudogiant-xr/Pseudolife-MCP.git
cd Pseudolife-MCP
ops/install.sh          # Linux / macOS
ops\install.ps1         # Windows (pwsh 7+)
# Codex: add --client codex / -Client codex
# Codex defaults to automatic hook-source detection and asks once for approval.
# Unattended hook approval: --codex-hook-trust yes / -CodexHookTrust yes
# Instructions only: --codex-hooks skip --instructions append
# PowerShell equivalent: -CodexHooks skip -Instructions append
# Both:  add --client both  / -Client both
# Gemini: add --client gemini — or several: --client claude,codex,gemini
# Other MCP agents (Cursor, Windsurf, Zed, ...): --client generic

安装程序首先会询问记忆库的位置：这台机器上（默认选项，以下说明均基于此选项）、另一台已运行该服务的机器上（仅安装客户端，需要输入守护进程的 URL 和令牌），或这台机器上并允许其他机器连接（参见在多台机器之间共享一个记忆库）。接着会询问要接入哪些 Agent（多选，并显示能力矩阵，准确列出每个 Agent 能获得的功能 — 会话简报、每轮操作规范、常驻文件），运行预检（为每项缺失的前置条件提供一条准确的修复命令），然后询问要使用哪种梦境提取器来整合记忆 —

• sidecar — 捆绑的本地 CPU 模型；无需 Claude 方案，适合所有人使用，并将所有记忆保留在本机（镜像约 11.8 GB）；
• claude-only — 最轻量的安装：通过 CLI shim 使用 Claude 模型（自 2026-09-29 起默认使用 claude-opus-5-5，该模型已通过相对于 claude-opus-5 的提取阶梯门槛；需要已登录 Max 方案的 claude CLI）； 不会构建或拉取 sidecar 镜像（轻约 11.8 GB；shim 不可用时，dream 会暂停）；
• claude-fallback — 以 Claude shim 为主，捆绑的 sidecar 自动作为备用方案（需要 Max 方案 CLI 和约 11.8 GB 的镜像）；
• openai-only / openai-fallback — 在 OpenAI 订阅下提供相同的两种模式：通过已登录 ChatGPT 方案上的 Codex CLI shim 使用 GPT-5.6 或 GPT-6 模型（默认使用 Terra；提取质量尚未测量 — 参见 dreaming 指南）；
• endpoint / endpoint-fallback — 使用你指定的任何兼容 OpenAI 的服务（--extractor-url、--model：LM Studio、Ollama、vLLM、托管 API），可单独使用，也可将 sidecar 作为备用方案。早期名称 sonnet-* 和 codex-* 仍可作为已弃用的拼写使用 — 随后启动整个栈，为选定客户端安装会话钩子 （客户端支持钩子系统时），注册 MCP 传输方式（默认使用 stdio shim，并为每个提供方分配 writer id；通过 --transport http 使用直接 HTTP），并对守护进程执行健康检查——最后逐个 Agent 列出已接入的内容，以及该 Agent 的平台无法支持的功能。Codex 设置提供一个选项，用于启用自动记忆简报、提醒和会话清理（此外，在 Agent 看板已启用时，还会在会话开始时检查看板，并在每条提示词中提示新邮件）；也可以选择仅使用常驻指令，或跳过。 自动设置会复用已启用的 PseudoLife 插件，或安装三个生命周期钩子；备份配置，仅批准其当前的精确定义，并验证执行情况。如果验证失败，同一批准也允许将常驻记忆块作为后备方案；设置过程会报告仍需修复的步骤。对于没有钩子机制的提供方（Gemini CLI 和通用 Agent），系统会提供常驻指令块。--instructions append 始终会将 examples/CLAUDE.memory.md 中的指令块写入 ~/.claude/CLAUDE.md / ~/.codex/AGENTS.md / ~/.gemini/GEMINI.md （即使使用钩子，这也有助于子 Agent 获取这些内容）。 支持幂等操作，可随时重新运行；--extractor <mode> 可切换提取器设置。非交互式示例： ops/install.sh --extractor sidecar --client codex --codex-hook-trust yes。 如果未明确批准钩子，无人值守设置不会授予信任；如需仅添加指令，请使用 --codex-hooks skip --instructions append。显式指定 --instructions skip 可阻止后备方案修改文件。 安装程序还会启用 Agent 看板：它会在 ops/.env 中生成一个 bearer token（仅所有者可访问，绝不会打印），并为其接入的每个 shim 客户端提供一个仅所有者可访问的 token 文件。在现有安装上重新运行时，会将该文件原地添加到 Claude Code 注册项中。清单的最后一行以及 pseudolife-mcp doctor 会说明看板是否已启用，或解释其未启用的原因。 使用 doctor --host codex 或 --host claude-code 获取简洁的协调状态快照：可达性、bearer 凭据准入、注册证据、工具清单和已配置的唤醒方式分别显示。默认的 doctor 为只读；健康状态正常且已配置唤醒路径，并不能证明消息已送达。协调诊断快速入门 介绍了已保存实例检查以及明确标记为可丢弃的邮件验证。 --no-token / -NoToken 会保留开放环回安装，同时让看板保持休眠状态（启用看板）。 Linux（Docker Engine）：你的用户必须属于 docker 组—— 运行 sudo usermod -aG docker $USER，然后注销并重新登录（预检会检查这一点）。

镜像大小、Windows WSL2 内存上限，以及安装程序会自动执行的操作： 请参阅下文的容器化安装（适用于任何操作系统）。

ops/preflight.sh --client codex    # or ops\preflight.ps1 -Client codex
docker volume create pseudolife-mcp-bank
docker volume create pseudolife-mcp-state
docker compose -f ops/docker-compose.yml up -d --build   # first build, once

# ...or pull the prebuilt images instead of building (releases >= 0.14.0):
docker compose -f ops/docker-compose.yml -f ops/docker-compose.ghcr.yml pull pseudolife-pg pseudolife-daemon
docker compose -f ops/docker-compose.yml -f ops/docker-compose.ghcr.yml up -d

# Verify, then wire the transport into one or both clients.
curl http://127.0.0.1:8765/health

# Stdio shim (the installer's default — per-session episode identity).
# PSEUDOLIFE_MCP_NO_SPAWN=1 makes the shim wait for the container instead
# of spawning a host fallback that can shadow the Docker bank after a
# reboot; set it on Docker-tier registrations like these.
pip install pseudolife-mcp
claude mcp add --scope user pseudolife-memory --env PSEUDOLIFE_MCP_NO_SPAWN=1 -- pseudolife-mcp
codex mcp add pseudolife-memory --env PSEUDOLIFE_MCP_NO_SPAWN=1 -- pseudolife-mcp

# ...or direct HTTP (no pip package needed; fine for single-session setups):
claude mcp add --transport http --scope user pseudolife-memory http://127.0.0.1:8765/mcp
codex mcp add pseudolife-memory --url http://127.0.0.1:8765/mcp

# Reinforce the protocol-level memory loop with a global standing instruction:
cat examples/CLAUDE.memory.md >> ~/.claude/CLAUDE.md
cat examples/CLAUDE.memory.md >> ~/.codex/AGENTS.md
# (PowerShell: Add-Content "$env:USERPROFILE\.claude\CLAUDE.md" (Get-Content examples\CLAUDE.memory.md -Raw))

一个通过 MCP 暴露的记忆引擎。它没有聊天界面，也没有负责思考的大模型——你的编码 Agent 才是智能所在；它会调用这些工具来存储和回忆重要信息。（模型确实作为基础设施的一部分被打包：用于检索的内置嵌入权重，以及可选的 CPU 提取器 sidecar，可在你休息时将记忆归纳为事实。）

它在 Agent 记忆常见方案中的定位——每一列都是适合其用途的工具；这张表讨论的是每种方案回答什么问题，而不是谁对谁错：

自动日志记录 Agent 做了什么；Pseudolife 整理它学到了什么。两者都很有用——它们回答的是不同的问题。具名替代方案——Mem0、Zep/Graphiti、Letta、Cognee、memU、Memori——以及更适合选择其中某个方案的情况： 比较。

它叠加了多个互补的存储：关联存储（一个扁平的嵌入存储，按余弦相似度排序，并与 BM25 词法候选池融合（默认启用），支持感知冲突的准入和显式源笔记替换；还可选择启用 8 层分带布局）；皮层（按槽位键控的规范事实——每个 entity.attribute 只有一个当前值，集合类型槽位则保存成员集合——具备来源分级，并会停放竞争值，而不是静默覆盖）；基于这些事实构建的类型化知识图谱，采用封闭的关系词汇表并在读取时进行推理；世界皮层（关于外部现实的持久带引用事实，信任度会随时间衰减）；从 Agent 自身工作中学到的流程经验；以及用于文档 RAG 的参考资料库，自 schema v57 起存储在库中。规范层的详细介绍： 记忆模型；图谱和多跳回忆： 检索。

状态存储在 Postgres 中（持久的事实来源），由一个长期运行的守护进程管理；每个会话都通过精简的 stdio shim（安装程序默认方式——每个会话使用独立身份）或直接通过 HTTP（单会话设置）连接。结果是：Claude 可以接续上次的工作，在事实变化时修正自身，并对关系进行推理——无需你在每个会话中重新解释上下文。

Documentation

本 README 是入门指南，涵盖安装、连接和基本工作流程。深入内容请参阅用户指南：

另请参阅 evals/README.md（完整的基准测试方法）和 贡献指南。

提供的工具

工具接口于 2026-07-02 完成整合（从 55 个减少到 32 个；加入 memory_toolset、set-slot 工具对和协调功能后，目前为 38 个）：生命周期类别改为按动词分发的工具 （memory_dream、memory_forget、memory_graph_review），而 转储/内省视图则移至 Cortex Console（REST）——清单是每个会话中 Agent 的上下文，因此保持精简。

工具集层级。 工具分为三个可见性层级——minimal（10 个工具）、core （24 个）和 full（38 个）——在 tools/list 中按主体进行筛选；主体（具名的持有者令牌身份，或单令牌安装中的写入者 id）可在调用隐藏工具前，通过 memory_toolset 调高或调低自己的层级。默认设置、按客户端配置的映射，以及弱模型部署方式： 配置 — 工具集层级。

架构

一个记忆守护进程负责管理记忆库，并通过 /mcp 上的可流式 HTTP 提供 MCP 服务；每个 Claude Code 会话（以及任何 LAN Agent）都连接到该服务。 Postgres 18 + pgvector（持久化层使用 Docker；精简层则以嵌入式方式运行相同的 Postgres，无需容器）是持久化事实来源—— 内存存储是一个写穿缓存，启动时会从持久化层载入（CMS 计数器也存储在记忆库中，自架构 v57 起位于 cms_counters；没有 MLP 权重）。

守护进程可以在容器中运行（推荐——可移植，无需主机 Python），也可以作为主机进程运行。Claude Code 通过一个精简、无 torch 依赖的 stdio shim 连接（安装器默认设置——每个会话使用独立身份，支持并发会话），也可以直接通过 HTTP 连接（更简单，适合单个会话）：

Claude session A ─┐  stdio shim (installer default) or HTTP
Claude session B ─┼───────────────────► pseudolife-mcp daemon ─► Postgres (Docker)
LAN agent ────────┘  or stdio shim         (single writer)        pgvector
                     (per session)         host proc OR Docker

这从设计上消除了 v0.1 的两个隐患：单一写入者意味着并发会话不会互相覆盖，而条目采用事务处理，因此崩溃不会清空记忆库。系统会强制执行单一写入者机制：守护进程会在其记忆库上持有 Postgres advisory-lock writer lease。第二个守护进程，或通过服务打开在线记忆库的脚本或评估程序，都会拒绝启动，并指出持有锁的进程。执行 ops/dedup_cortex.py 等离线维护操作前，请先停止守护进程。如果记忆库在启动时加载失败，守护进程就不会提供任何服务，而不会提供部分加载的记忆库；在重试成功之前，/health 会报告 degraded 及其原因。在关联式存储之上是规范层——cortex、world facts、lessons、temporal/HLC 时间戳 （记忆模型）——它们连接到一个类型化知识图谱，可通过 memory_graph 和多跳 memory_recall 遍历 （检索与图谱）。

安装 — 容器化（适用于任何操作系统）

上面的持久层安装器所做的操作，手动执行一遍。整个堆栈——Postgres 和记忆守护进程——都在 Docker 中运行。 无需在主机上安装 Python，也无需安装 torch，没有版本不一致问题；守护进程镜像内置了仅支持 CPU 的 torch 和嵌入权重——Qwen/Qwen3-Embedding-0.6B （自 schema v25 起的默认检索骨干模型）以及 all-MiniLM-L6-v2 （保留在镜像中，用于 ONNX 奇偶性测试路径）——因此在 Windows / macOS / Linux 上的运行方式完全一致。仅需 Docker；一次构建：守护进程镜像约 5.0 GB （根据部署版本于 2026-07-29 测得）+ Postgres 约 0.6 GB + 提取器 sidecar 约 11.8 GB（使用 v3 多任务构建版本于 2026-08-20 测得； 使用安装器的 claude-only 模式可完全跳过 sidecar）。 2026-07-29 之前公布的约 12.6 GB 和 10.4 GB 数值已作废：这两个数值都因依赖解析错误将 CUDA torch 构建引入镜像而偏高（参见 CHANGELOG）；守护进程始终仅使用 CPU。

git clone https://github.com/Pseudogiant-xr/Pseudolife-MCP.git
cd Pseudolife-MCP

# 1. One-time: create the two persistent volumes (bank + daemon state).
docker volume create pseudolife-mcp-bank
docker volume create pseudolife-mcp-state

# 2. Build + start all three services (Postgres, extractor, then the daemon).
docker compose -f ops/docker-compose.yml up -d --build

或者跳过约 5 GB 的守护进程构建，拉取预构建镜像 （releases ≥ 0.14.0）：

docker compose -f ops/docker-compose.yml -f ops/docker-compose.ghcr.yml pull pseudolife-pg pseudolife-daemon
docker compose -f ops/docker-compose.yml -f ops/docker-compose.ghcr.yml up -d

提取器 sidecar 尚未发布，仍需在本地构建；请使用 pseudolife-mcp update 更新拉取路径（备份、固定镜像、回滚标签；参见更新），不要直接执行 pull + up -d。

从重命名前的安装版本升级（卷 ops_pseudolife_pgdata / ops_pseudolife_data）？不要重命名这些卷——在运行 up 前，创建 ops/.env 并设置 PSEUDOLIFE_BANK_VOLUME=ops_pseudolife_pgdata 和 PSEUDOLIFE_STATE_VOLUME=ops_pseudolife_data，让系统继续使用这些卷。参见 compose 文件头部。

**Windows：**限制 Docker Desktop 的 WSL2 虚拟机内存，否则它可能占用多达 主机 RAM 的约 50%。有关堆栈实际需要的内存、ops/wslconfig.example 模板，以及守护进程容器自身的内存上限，请参见：配置 — Windows / WSL2 内存。

守护进程通过 http://127.0.0.1:8765/mcp 提供 MCP 服务，并随 Docker 一同重启——无需登录任务。首次构建时会将模型下载到镜像中（仅一次）；此后每次启动容器都无需联网，且启动迅速。通过 stdio shim（安装器默认方式）或直接通过 HTTP 接入 Claude Code（见下文）。有关数据的实际存放位置以及 如何备份，请参见： 配置 — 数据布局。

**其他机器，共用一个知识库：**笔记本电脑、服务器或容器中的会话也可以使用此守护进程，只需进行仅安装客户端的安装，运行 shim 即可。有关如何公开守护进程（Tailscale Serve、局域网发布或反向代理）、按机器配置令牌以及看板准入的信息，请参见： 多台机器共用一个知识库。

**主机进程安装（Windows，适用于 GPU / 开发）：**在 Docker 中运行 Postgres，但让守护进程运行于主机 Python——适用于开发守护进程，或在本地 GPU 上运行嵌入模型。步骤、pseudolife-mcp CLI 模式以及登录时自动启动任务，请参见： 配置 — 主机进程安装（Windows，适用于 GPU / 开发）。

更新

从尚无 Agent 看板（还没有 bearer token）的版本升级：此迁移步骤适用于由安装器管理的 Docker 安装。使用相同的客户端选择重新运行 ops/install.ps1（Windows）或 ops/install.sh（Linux / macOS） （会话可以保持打开：shim 会作为新的运行时安装在当前运行版本旁边）。 安装器会为默认 shim 安装创建 bearer token，并就地迁移 Claude Code 中由安装器管理的 pseudolife-memory stdio 注册项的环境配置。自定义注册项会保留；对于 Gemini 或自定义注册项，请按安装器打印的凭据警告操作。-All / --all 和 ops/update_clients.py 不会 创建令牌，也不会迁移注册项环境配置。然后按照下文的一次性完成所有更新方案刷新客户端并重启。 以 Pseudogiant-xr/Pseudolife-MCP 添加的插件市场（安装程序最高至 0.16.1）会通过 SSH 刷新，因此在没有 GitHub SSH 密钥的机器上会失败。pseudolife-mcp update 和安装程序会自行将其切换到 HTTPS URL，并创建备份。如果这一步报告失败，手动备用方案是：在 settings.json（$CLAUDE_CONFIG_DIR，否则为 ~/.claude）中，将 extraKnownMarketplaces 下 pseudolife-mcp 条目的 source 设为 {"source": "git", "url": "https://github.com/Pseudogiant-xr/Pseudolife-MCP.git"}， 然后运行 claude plugin marketplace add https://github.com/Pseudogiant-xr/Pseudolife-MCP.git （绝不要运行 marketplace remove：那会卸载插件）。

**一条命令，无需检出代码：**已安装的 shim 会从一个发行版更新整个安装：

pseudolife-mcp update            # the newest release on PyPI
pseudolife-mcp update --tag 0.15.1
pseudolife-mcp update --check    # exit 0 when a newer release exists, 3 when current

首次从 0.15.0 或更早版本更新时没有此命令（该 shim 会回复“unknown mode”，而该守护进程也不会发布发行版通知）：如果已检出代码，运行 git pull，然后运行 ops/update.sh --all 或 ops/update.ps1 -All；如果通过 pipx 或 pip 安装，则运行 pipx install --force "pseudolife-mcp[lite]==<version>" 或 pip install --upgrade "pseudolife-mcp[lite]==<version>"（仅 lite 安装才使用 [lite] 附加项）。之后，pseudolife-mcp update 即可使用。在仅安装客户端的机器上（守护进程位于另一台主机），update 和 --clients-only 会将本机客户端更新到守护进程对应的发行版。

对于 Docker 层级安装，它会拉取固定版本的 GHCR 守护进程镜像，备份数据库（如果 compose 项目仍有检出代码，则使用其中的备份脚本；否则使用自身的 pg_dump + 状态卷 tar 备份到 ~/.pseudolife-mcp/ backups），为正在运行的镜像添加回滚标签，仅使用创建该容器时的 compose 文件（或检出代码已不存在时使用软件包自带副本）重新创建守护进程容器，等待 /health 显示新版本，然后将该发行版安装为一个与正在运行的版本并存的新 shim 运行时，刷新插件缓存并打印 Codex hook 步骤。备份会保留，供你查看和处置：这里不会自动将其清除。--clients-only / --daemon-only 可分别更新其中一部分；shim 本身从其注册位置运行，因此如果 pseudolife-mcp 不在 PATH 中，请使用其完整路径。对于 pip / lite 安装，它会在安装该软件包的解释器中升级软件包（pip 或 pipx），不会重启任何服务：它会告诉你需要重启什么。

系统会在需要时通知你：守护进程会在后台查询 PyPI，获取最新发行版（updates.check_releases，默认开启），随后每个会话的简报都会以 release X is available — run pseudolife-mcp update 开头。在 config.yaml 中设为 updates.unattended_clients: true（默认关闭）后，每当守护进程版本较新时，守护进程主机上的 Docker 层级 shim 会自行将守护进程的发行版安装为新的运行时并刷新插件缓存；重新创建守护进程仍需手动执行命令。 在无头主机上，pseudolife-mcp update --schedule 03:30 会安装每日任务或计时器，仅当 updates.unattended_daemon: true 且 Agent 看板上没有活动会话时才会应用新发行版；该操作会使用相同的备份和回滚标签，并在看板上发布通知，无论成功与否。Codex 会在更新后保留其 hook 授权（授权的是 hook 定义，而非脚本），并且从检出代码更新时会自动刷新手动复制的 Codex hook。当 Codex 运行插件的 hook 时，客户端步骤会通过 codex plugin marketplace upgrade 刷新 Codex 中已安装的插件副本，同时保持已授权的 hook 定义不变（Codex 特定说明）；只有 hooks.json 发生变化时，每种更新方式才会打印授权步骤。 参见更新。

**手动更新 Lite 层级：**一条命令，不动数据库：

pip install -U "pseudolife-mcp[lite]"

在 Windows 上，先退出所有使用 shim 的 Claude Code、Codex 和 Claude Desktop 会话（从系统托盘退出 Desktop）：升级正在运行的程序包可能导致它被卸载一半。

从代码库检出版本部署 Docker 层：执行 git pull（或修改本地代码）后，只重新部署守护进程——安全操作，不会触碰 Postgres 或提取器：

.\ops\update.ps1        # Windows

./ops/update.sh         # Linux / macOS

两者都是同一个 Python 部署命令 pseudolife-mcp update 的轻量封装（ops/update.py → pseudolife_memory/update_cli.py），因此只有一份实现。它会备份 bank（使用 pg_dump 和状态卷 tar 包），标记一个回滚镜像（若存在上一版本镜像；若不存在，会明确提示），仅重新构建并创建守护进程，然后等待 /health。它绝不会运行 down -v。（主机进程安装：只需重启守护进程——pip install -e . 使用可编辑安装。）每次部署健康后都会自动清理构建缓存；每周 Scheduled Task 和手动压缩 .vhdx 请参阅Docker 磁盘保留。切勿运行 docker system prune --volumes，它会删除卷。

镜像会记录其构建所用的提交，/health 会通过 build 字段报告这些信息（git_sha、dirty、built_at 和 source：checkout 或 release）。因此，脚本会拒绝包含未提交或未跟踪文件的工作树，并列出这些文件。它也会拒绝 Git 无法描述的工作树（没有 Git、不是克隆仓库，或 Git 拒绝 safe.directory；拒绝原因会原样引用）。请先提交或清理文件，或者传入 -AllowDirty / --allow-dirty，按当前状态部署工作树：标记为 dirty: true；若 Git 无法描述，则标记为 unknown。每次部署都会构建新镜像，因此即使提交没有变化，也会重新创建守护进程容器。

**一次性更新所有内容：**守护进程是三种安装方式之一。客户端启动的 shim 和 Claude Code 插件是独立组件，不会随守护进程一起更新。传入 -All / --all，即可在同一次运行中更新它们，并且会在守护进程健康后执行：

.\ops\update.ps1 -All   # Windows

./ops/update.sh --all   # Linux / macOS

shim 步骤无需关闭任何会话。每个 shim 版本都会安装到各自的运行时中（Windows 上为 %LOCALAPPDATA%\pseudolife-mcp\runtimes\NNNNNN，其他系统上为 ~/.local/share/pseudolife-mcp/runtimes/NNNNNN），每个客户端都会注册同一个启动器路径（%LOCALAPPDATA%\pseudolife-mcp\bin\pseudolife-mcp.exe / ~/.local/share/pseudolife-mcp/bin/pseudolife-mcp），由它启动最新的完整运行时。安装程序和更新步骤还会让你在终端中输入 pseudolife-mcp 时调用启动器。在 Linux 和 macOS 上，~/.local/bin/pseudolife-mcp 会变成指向启动器的链接；如果那里已有旧的 pipx 或 pip --user 入口，会将其移到一旁并命名为 pseudolife-mcp.<kind>-<stamp>（绝不会删除），其他内容则保持原样并予以标注。如果 ~/.local/bin 不在 PATH 中，此步骤会打印需要添加到 shell 配置文件的行：export PATH="$HOME/.local/bin:$PATH"。在 Windows 上，启动器目录会排在用户 PATH 的首位，优先于 pipx 和 pip 的副本；要让命令名调用启动器，请打开新终端，因为已打开的终端仍使用旧的 PATH。pseudolife-mcp doctor 会报告命令名解析到的位置（path_resolution），并在解析结果不是启动器时发出警告；启动器的完整路径始终可用。 此步骤会将当前检出安装为与旧运行时并列的新运行时，将仍指向运行时、pipx 或 virtualenv 路径的注册原位改为指向启动器（Claude Code、Codex、Claude Desktop 和 Gemini CLI；每个文件都会先备份为 <file>.bak-<stamp>），并在没有进程从旧运行时运行且没有注册指向它们后，移除旧运行时。已经运行的会话会继续使用启动时所用的运行时；下一次启动会话时则使用新运行时。若 shim 直接从此检出的 .venv 运行，则它已是最新状态，步骤会对此作出说明。随后，如果插件缓存与 marketplace 克隆的字节不同，步骤会刷新插件缓存（claude plugin update 会将新副本安装在正在运行的会话所用副本旁；不会卸载任何内容），并报告 Codex 的 hook 副本是否与当前检出一致（此刷新需要征得同意：python ops/setup-codex-hooks.py）。最后会列出哪些内容已迁移，以及哪些客户端需要重启；客户端侧步骤即使失败也会报告，但不会导致部署失败。同一辅助程序也可独立运行：python ops/update_clients.py；python ops/shim_runtime.py 可手动管理运行时（install、list、prune、migrate）。自定义注册会保留并予以标注；请在各自的解释器中升级它们。若守护进程侧凭据已更改，但 shim 仍是旧版本，两者就会不同步：Claude Desktop 注册器会拒绝无法读取所选令牌文件的 shim（退出码 4），并提示升级。

• 升级到 2026-09-28 之后的版本：看板邮件会开始唤醒空闲会话。 插件缓存和 shim 更新后（-All，然后重启客户端），收到的邮件若满足会话暂停等待的条件，Claude Code 会话和使用 codex CLI 的 Codex 任务就会被唤醒；此前这两种唤醒方式都需要手动启用。闲聊不会触发通知，且通知次数有限。若要保持旧行为，请在 ~/.claude/settings.json 的 env 块中设置 PSEUDOLIFE_AGENT_WAKE_HOOK=0，并在 Codex 服务的 env 表中设置 PSEUDOLIFE_CODEX_DOORBELL = "0"（在任一位置设置 PSEUDOLIFE_AGENT_COORDINATION=0 都会关闭该客户端的看板）。pseudolife-mcp doctor 会在 wake 下显示每个客户端的唤醒方式。 三者会相互印证：/health 会报告守护进程的 version，以及它随附的钩子脚本摘要；如果插件版本与守护进程版本不一致，或者版本匹配但钩子不匹配，会话简报开头会显示一行提示。版本不一致时，提示会指出要运行 /plugin marketplace update pseudolife-mcp，然后运行 /plugin update pseudolife-memory@pseudolife-mcp，或重新部署守护进程，具体取决于哪一方版本较旧；钩子不匹配时，提示会指出上文的 --all 命令。shim 会在 stderr 和操作说明之前显示提示；pseudolife-mcp doctor 则会报告 version_mismatch。

有两种升级不会自动进行，因为无法安全地就地完成。两者都有分步操作手册——备份、试运行、应用、验证、回滚；全新安装不需要这些步骤：

• 低于 0.11.0 版本的存储库（架构 v25）：所有嵌入列都从 vector(384) 迁移到了 vector(1024)，因此守护进程会拒绝启动，而不是只完成部分迁移。使用 ops/migrate_embeddings.py 离线重新嵌入—— v25 迁移操作手册。
• 在 2026-08-14 之前创建的 Docker 层存储库（PostgreSQL 16 → 18）： Postgres 主版本升级无法复用旧数据卷。运行 pwsh ops/migrate-pg18.ps1—— PostgreSQL 18 迁移操作手册。

接入你的编码 Agent

插件（钩子 + 命令）。 只要 Claude Code 是选定的客户端，安装程序就会添加此插件（--claude-plugin skip / -ClaudePlugin skip 可跳过；已安装的插件不会更改）。它会接入会话钩子（简报 + episode 身份）、记忆循环说明，以及 /dream + /memory-status 命令。也可以在 Claude Code 中手动运行相同的两个命令：

/plugin marketplace add https://github.com/Pseudogiant-xr/Pseudolife-MCP.git
/plugin install pseudolife-memory@pseudolife-mcp

该插件会替代 settings.json 钩子，守护进程则会提供精简的记忆核心和实时简报作为会话上下文。默认情况下（memory_policy.variant: compact），不会提供下方完整的 CLAUDE.md 内容块；如果你需要完整指南，可以将其附加进去。 插件有意不捆绑 MCP 服务：Claude Code 会加载插件服务以及任何用户注册的服务，且不会去重，这会导致每个会话的工具命名空间与安装程序的注册项重复——因此，传输只会通过 ops/install.*（默认使用 stdio shim——每个会话各自拥有 episode 身份）或下面的一行命令注册一次。 较早的安装写入 ~/.claude/settings.json 的钩子会与插件的钩子重复；插件运行后，安装程序会提示你移除这些钩子（无人值守时使用 --claude-legacy-hooks remove / -ClaudeLegacyHooks remove）。 详情、非默认端口/令牌及迁移说明： plugin/README.md。

手动注册传输。 安装程序默认使用 shim 模式，会注册一个轻量级 stdio shim——每个会话启动一个 shim 进程，因此每个会话都有自己的第 1 层身份。手动配置方式如下：

pip install pseudolife-mcp    # daemon in Docker; add [lite] for the pip tier
claude mcp add --scope user pseudolife-memory --env PSEUDOLIFE_MCP_NO_SPAWN=1 -- pseudolife-mcp

Docker 层注册项需要设置 PSEUDOLIFE_MCP_NO_SPAWN=1：这样 shim 会等待容器启动，而不是启动主机端备用进程；备用进程的端口绑定可能与尚未启动完成的 Docker 竞争，并抢占真正的存储库。在 [lite] pip 层中，请移除 --env——在那里，备用启动方式就是零配置路径。

也可以直接使用 HTTP——守护进程原生支持通过 HTTP 提供 MCP（无需 shim、无需主机命令，也不依赖特定操作系统；此时并发会话会共享一个 episode 身份，因此最适合单会话配置）：

claude mcp add --transport http --scope user pseudolife-memory http://127.0.0.1:8765/mcp

（--scope user 会为每个项目注册；移除它则只会为当前项目注册。）你也可以自行编写等效的 JSON——用户级配置放在 ~/.claude.json 的顶层 mcpServers 键下，项目级配置放在项目根目录的 .mcp.json 中：

{
  "mcpServers": {
    "pseudolife-memory": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

对于受令牌保护的守护进程，请在该 Claude JSON 条目中添加 headers 键： "headers": { "Authorization": "Bearer <your-token>" }。 Claude Desktop（应用本身，包括其 Cowork 和 Code 会话）——安装程序会为你写入条目：

ops/install.sh --client claude-desktop      # Windows: ops\install.ps1 -Client claude-desktop

Desktop 没有 mcp add；其服务配置位于 claude_desktop_config.json （macOS ~/Library/Application Support/Claude/，Linux ~/.config/Claude/， Windows %APPDATA%\Claude\——但 Store/MSIX 版本例外，其实际文件位于 %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\；如果该路径存在，安装程序会优先使用）。手动添加的等效条目：

{
  "mcpServers": {
    "pseudolife-desktop": {
      "command": "/absolute/path/to/pseudolife-mcp",
      "env": {
        "PSEUDOLIFE_WRITER_ID": "claude-desktop",
        "PSEUDOLIFE_MCP_NO_SPAWN": "1",
        "PSEUDOLIFE_MCP_DAEMON_URL": "http://127.0.0.1:8765"
      }
    }
  }
}

该条目有意命名为 pseudolife-desktop。Desktop 的 Code 选项卡运行 Claude Code，它会启动自己的、按会话隔离的 pseudolife-memory 服务；如果应用级条目使用相同名称，Desktop 会将会话的 mcp__pseudolife-memory__* 调用发送到应用级条目，而会话自己的服务则不会收到任何调用。重新运行安装程序时，它会重命名自己在旧名称下写入的条目（其 env 将 PSEUDOLIFE_WRITER_ID 设为 claude-desktop），保留你添加的所有 env 键，并先备份配置。其他任何 pseudolife-memory 条目都会原样保留，并显示警告。随后，Chat 和 Cowork 会将这些工具列为 mcp__pseudolife-desktop__*。

与 CLI 客户端相比，有两点不同。Desktop 会在经过清理的环境中启动 MCP 服务——只有 PATH 和少数系统变量，不包含 shell 导出的任何变量——因此，command 必须填写 shim 的绝对路径（which pseudolife-mcp / Get-Command pseudolife-mcp）；受令牌保护的守护进程还需要在该 env 块中设置 "PSEUDOLIFE_MCP_TOKEN_FILE": "/absolute/path/to/a/private/file"：在操作系统环境中导出的 bearer 令牌不会传递到 shim。忘记设置时的表现是每个会话都失败，并显示 "Couldn't start for Cowork and Code sessions. Error: unhandled errors in a TaskGroup (1 sub-exception)"——SDK 包装层下的 401 错误；现在 shim 会在启动时通过 stderr 明确说明错误。如果守护进程受令牌保护，安装程序会从其环境变量或 ops/.env 中的 PSEUDOLIFE_MCP_TOKEN 创建该文件（仅所有者可访问），或将条目中已有的字面令牌迁移到该文件；如果没有可写入的令牌，它会说明情况并以状态码 3 退出。shim 还必须能够读取该文件： 0.15.0 及更早版本仅读取字面值 PSEUDOLIFE_MCP_TOKEN，因此注册程序会先通过 <command> --help 检查文件形式；如果 shim 版本过旧，就会拒绝注册（状态码 4，不写入任何内容），而不是注册一个会出现相同 TaskGroup 错误的条目——请升级 shim（重新运行安装程序，或在检出目录中运行 python ops/update_clients.py --only shim：它会在正在运行的运行时旁安装新运行时，因此无需关闭任何会话），然后重新运行。编辑后，务必通过托盘或菜单栏图标完全退出 Desktop 并重新启动——关闭窗口不会重新加载配置。

Codex——安装程序默认的 shim 模式会接入相同的 stdio shim，因此 Codex 会话会获得自己的 tier-1 身份，而不是继承并发 Claude 会话的 episode：

pip install pseudolife-mcp
codex mcp add pseudolife-memory --env PSEUDOLIFE_MCP_NO_SPAWN=1 -- pseudolife-mcp

（与上文 Claude 接入方式相同的 Docker-tier 说明：守护进程在 Docker 中运行时，保留 PSEUDOLIFE_MCP_NO_SPAWN=1；使用 [lite] pip tier 时则移除。）

HTTP 单行命令也可用（无需 pip 包）：

codex mcp add pseudolife-memory --url http://127.0.0.1:8765/mcp

或者，在 ~/.codex/config.toml 中添加等效的用户级条目：

[mcp_servers.pseudolife-memory]
url = "http://127.0.0.1:8765/mcp"
bearer_token_env_var = "PSEUDOLIFE_MCP_TOKEN"

对于该 Codex HTTP 配置，请在启动 Codex 的环境中导出 PSEUDOLIFE_MCP_TOKEN。令牌不会写入 config.toml，Codex 会在连接时读取它。默认的 stdio shim 无需此设置。

Gemini CLI——配置形式相同（-s user 很重要：Gemini 默认使用项目作用域；-e 环境变量会为 Gemini 会话提供单独的写入归属；同样适用上文的 Docker-tier PSEUDOLIFE_MCP_NO_SPAWN=1 说明）：

pip install pseudolife-mcp
gemini mcp add -s user -e PSEUDOLIFE_WRITER_ID=gemini -e PSEUDOLIFE_MCP_NO_SPAWN=1 pseudolife-memory pseudolife-mcp

或者使用 HTTP，无需 pip 包：

gemini mcp add -s user -t http pseudolife-memory http://127.0.0.1:8765/mcp

注意：自 2026-06-18 起，Google 不再通过 Gemini CLI 为个人级账户（免费、AI Pro、AI Ultra）提供服务 — OAuth 登录会失败并指向 Antigravity。上述配置仍然正确，但个人账户需要使用 API 密钥认证（GEMINI_API_KEY）才能实际运行会话 — 或使用 Google Antigravity 本身，它通过 ~/.gemini/config/mcp_config.json 连接到同一个记忆库；两种方式均见提供商指南。

任何其他支持 MCP 的 Agent（Cursor、Windsurf、Zed、Copilot CLI 等）— 将通用的 mcpServers 条目添加到该工具的 MCP 配置中（ops/install.sh --client generic 会输出两种可直接粘贴的格式）：

{
  "mcpServers": {
    "pseudolife-memory": {
      "command": "pseudolife-mcp",
      "env": {
        "PSEUDOLIFE_WRITER_ID": "mcp-client",
        "PSEUDOLIFE_MCP_NO_SPAWN": "1"
      }
    }
  }
}

各 Agent 能获得什么 — 以及其平台不支持什么（钩子、逐轮规范）：提供商矩阵。

**验证：**运行 claude mcp list、codex mcp list 或 gemini mcp list （服务应报告已连接），然后让 Agent “存储一条记忆，记录此安装有效”，并检查它是否出现在控制台的 Stream 视图中：http://127.0.0.1:8765/ui/。

更倾向使用 stdio（这是安装程序默认配置的方式，可按会话识别身份）？一个不依赖 torch 的轻量垫片可将 stdio 代理到守护进程： stdio 垫片 · 在多台机器间共享一个记忆库 · 备份与恢复演练 · Agent 邮箱恢复。

推荐的 Agent 设置（CLAUDE.md / AGENTS.md）

服务的价值取决于 Agent 是否使用它。MCP 服务通过协议级 instructions 提供核心循环；其协调适配器启动后，垫片会添加消息板签到。 插件的记忆 SessionStart 钩子（也用于已验证的 Codex 钩子）会提供简短的操作指南和有限范围的简报；如果没有插件，安装程序配置的 Claude Code settings.json 钩子 （pseudolife-mcp briefing --hook-json）也会提供相同的两项内容。 另一个单独的协调钩子会要求 Agent 设置其项目、任务和状态，发现同伴并阅读待处理消息，但仅在该凭据启用了消息板时才会运行（默认情况下，消息板在承载令牌认证的情况下启用，因此开放式安装或已禁用的消息板不会触发签到）。 详细的记忆 指南仍保留在随附的常驻指令块中。钩子会添加逐提示词提醒和会话记录；两种传递方式都无法保证模型会执行每项所要求的记忆操作。

默认情况下（memory_policy.variant: compact），钩子最多只提供这份简短指南，而详细指令块仅作为常驻副本提供给 Agent（full_separate_hook 变体会通过单独的钩子提供该内容；请参阅 启动记忆策略）。 如需完整指南、让子 Agent 能看到内容（子 Agent 会读取 CLAUDE.md，但不会读取钩子输出），或用它替代钩子，请将其附加到 Claude 的全局 ~/.claude/CLAUDE.md、Codex 的全局 ~/.codex/AGENTS.md、Gemini 的全局 ~/.gemini/GEMINI.md，或项目级 CLAUDE.md / AGENTS.md 中：

cat examples/CLAUDE.memory.md >> ~/.claude/CLAUDE.md
cat examples/CLAUDE.memory.md >> ~/.codex/AGENTS.md
cat examples/CLAUDE.memory.md >> ~/.gemini/GEMINI.md

Add-Content "$env:USERPROFILE\.claude\CLAUDE.md" (Get-Content examples\CLAUDE.memory.md -Raw)
Add-Content "$env:USERPROFILE\.codex\AGENTS.md" (Get-Content examples\CLAUDE.memory.md -Raw)

对于没有钩子的提供商，此常驻指令块会提供完整的记忆策略，但无法提供实时简报或运行会话清理。AGENTS.md 是跨厂商的常驻 Agent 指令标准（由 Linux Foundation 管理；Codex、Copilot、Cursor、Gemini CLI、Zed 及其他 30 多种工具都会读取），因此，项目级 AGENTS.md 中若包含该指令块，几乎可同时覆盖所有 Agent。Claude Code 是个例外 — 它读取 CLAUDE.md — 但如果 CLAUDE.md 的首行是 @AGENTS.md，就会导入共享文件，因此一份副本即可供所有工具使用。 该区块（examples/CLAUDE.memory.md）介绍了这一循环：开始时回忆（memory_search / memory_lesson_search / memory_fact_get / memory_world_search），过程中记录（使用如实的 origin 调用 memory_store，用 memory_fact_set 记录规范事实，用 memory_world_set 记录带引用的外部事实；对于冗长日志，使用 source="status"，以免它们进入梦境），结束时反思 （调用 memory_outcome，用 used_ids 列出你实际用到的命中项——梦境会提炼这些信号，形成你下次会话开始时呈现的经验）。

对于现有的 Codex 安装，请运行 python ops/setup-codex-hooks.py。 该助手只会询问一次，会检测钩子来源，备份已更改的配置，通过 Codex 保存指定范围的信任设置，并验证启动简报、提示提醒和会话清理， 以及在 Agent 看板已启用时的签到步骤。Docker 安装程序会替你运行此步骤。 参见 Codex 设置选项和备用方案。

对于 Claude Code，请使用插件，或使用旧版 ops/install-hook.ps1 -Client claude / ops/install-hook.sh --client claude 安装简报和提醒钩子。旧版 --client codex 路径仍可用，但只会写入钩子定义；不会完成信任设置和验证。即使没有钩子，会话片段也能通过守护进程正常工作： 片段与会话。

当前 Codex 运行时默认启用钩子，包括 Windows。 钩子是否可用取决于应用程序／运行时和策略，而非模型。 如果有意设置 [features] hooks = false，请保留该设置并使用常驻的 AGENTS.md 区块。Codex 会将插件的 Windows 钩子作为原生 PowerShell 7 命令运行；Claude Code 则通过 Git Bash 运行这些钩子的 Bash 命令，因此需要安装适用于 Windows 的 Git（参见 plugin/README.md）。 参见官方钩子协议。

**Codex 钩子信任：**设置时的批准仅适用于 PseudoLife 当前的钩子 定义：记忆和协作的 SessionStart 与 UserPromptSubmit 处理程序，以及 SessionEnd；此外，使用插件时还包括其 Stop 项（Claude Code 中默认启用的唤醒钩子；在 Codex 中只运行停放门控）、其 SubagentStart 和两个 SubagentStop 处理程序（Claude Code 的子 Agent 看板钩子，在 Codex 中不执行任何操作，另加停放门控），以及其 PreToolUse 守卫。这不会批准其他插件，也不会绕过 未来的信任检查。同一授权还会为 pseudolife-memory 服务上的 memory_message 工具设置 approval_mode = "approve"，除非你自行设置其他值；这样一来，Codex 线程就能读取和发送看板邮件，而无需询问。Codex 批准的是定义，而不是这些定义运行的脚本，因此该批准也涵盖 PseudoLife 后续更新安装的脚本（对于手动复制的文件，更新程序会自行安装脚本并通过内容验证）。定义更改后需要重新批准，插件更新新增的处理程序也需要重新批准；在桌面应用中，Codex 会静默跳过未获批准的处理程序，而 pseudolife-mcp update（从检出目录运行时使用 ops/update.ps1 -All 或 ops/update_clients.py）会将其报告为 needs-approval。如果自动设置无法使用已安装运行时的信任接口，它会报告问题，并要求你打开 /hooks，检查并信任这些定义。已批准的常驻说明仍可作为备用方案。仅安装文件并不能证明钩子正在运行。

使用模式

会话开始时 — 加载你之前处理过的内容，可在压缩后继续保留：

memory_search("project context for X")

工作期间 — 存储真正的决策；跳过一时的闲聊（已发布的存储门槛较宽松，因此只记录经过审慎判断、长期有效的内容）：

memory_store("Decided to use stdio transport for the MCP because no port conflicts", source="pseudolife")

收到纠正时 — 将旧事实标记为已被取代，并且存储纠正后的内容；两者都会在后续检索中出现，新内容的排名更高。使用搜索结果或最近命中项中携带的 id 选择条目：

memory_supersede(
  entry_id=417,
  new_text="Provider interface uses async calls — sync version was the v0.7 prototype only"
)

当完整存储文本在有效条目中恰好唯一时，old_text= 仍可按该文本进行选择；它是旧版选择器，也是文件模式唯一支持的选择器。目标有歧义或不存在时，不会进行任何更改。

清理 — memory 和 fact 范围会硬删除（memory 范围至少需要一个筛选条件，以防意外批量删除；多个筛选条件会缩小匹配范围，因此 text="probe", source="status" 指的是该来源中的 probe 条目，而不是整个来源；如果匹配条目数超过 memory.delete_confirm_threshold — 默认值为 20，设为 0 可禁用 — 则会拒绝操作并返回 would_delete，直到再次调用并设置 confirm_bulk=true；在 Postgres 上，遗忘某个条目时，也会将其作为最后一个存续来源的当前事实、dream 边和经验教训退役，并保留为历史记录，同时将受影响的会话摘要加入重新生成队列）；lesson 和 world 范围会通过审计行将槽位退役，并可使用 memory_graph_review(action="restore_slot", store=..., src="entity|attribute") 撤销；若要“保留历史记录，但将其标记为错误”，请改用 memory_supersede：

memory_forget(scope="memory", source="test-noise")              # refused past 20 matches
memory_forget(scope="memory", source="test-noise", confirm_bulk=True)
memory_forget(scope="fact", entity="test-entity")

查看知识库中的内容： 打开 Cortex Console — 来源、标签、情节和完整表格视图都在那里。深入了解： 重新排序、BM25、弃答和追踪调试 · 情节 + 标签 · 规范事实、候选项、世界事实、经验教训 · 整合工作流。

梦境整理 — 将记忆整合为事实

梦境会在你不注意时，将近期的联想流提炼为规范的 cortex 事实：提取尚未整合的记忆 → 提取 (entity, attribute, value) → 持久确认这些确切条目。 新条目无论时间戳如何都会保持待处理状态；确认失败时，可能会重放声明应用。手动提交使用 pull 返回的令牌。提取方式可插拔：

该技术栈预配置了第 2 层（在 llama.cpp 侧车中运行的专用 Gemma 4 E4B 微调提取器，仅供内部使用）。有关扫描频率、将梦境指向更大的本地模型或 Claude Sonnet 并在侧车不可用时自动回退、完整语料库的深度梦境图谱处理，以及隐私与成本权衡，请参阅：梦境整理。

基准测试

醒目的成绩针对的是完整基准测试，而非其中一部分：覆盖 LongMemEval 的全部六种问题类型，共 500 道 题；使用 oracle 变体，通过记忆系统端到端运行（在 v25 嵌入骨干下使用 qwen-27b 提取，按轮次检索使用 BM25）。单次运行，由本地 Qwen3.6-27B 基准测试评审模型评分（2026-08-03）：

级联是一种服务策略，而非第四条流水线：当整合后的事实通道提交时，就根据其中的事实作答；若该通道弃答，则回退到原始轮次 RAG。总体而言，准确率持平，上下文量约为原来的 73%——单次运行的 500 道题中，0.690 对 0.688 只差一道题，不应将其解读为胜利。单独使用事实主干，token 预算约为 RAG 的 13%，但对于其设计目标之外的问题类型，准确率会大幅下降。各类型的结果如下：

整合后的主干在事实发生变化以及答案位于单个会话内时有所帮助；但当答案必须跨会话汇总或按时间排序时则表现较差，因为逐条事实整合恰恰会丢弃这些结构。BEAM-100K 独立复现了相同的趋势。主干在弃答问题上表现最佳——事实主干方案得分为 0.950，高于朴素 RAG 的 0.775；本地评审模型和独立的 Opus 级评审模型得分相同——但 2026-09-02 的五方案运行结果限制了这种解读：不使用记忆的方案在此得分为 1.000，因此优势来自校准（少量事实上下文会在原始轮次产生臆造时选择弃答），并非记忆确实回忆起了任何内容。设置、注意事项、两套基准测试的并列对比，以及提取质量是决定性因素的证据：基准测试；完整方法： evals/README.md。

在替换为 v25 骨干之前，我们已在同一语料上重新测量检索效果（150 道题、74,183 个候选轮次、299 个金标轮次；纯召回——不使用阅读器或评审模型）：Qwen/Qwen3-Embedding-0.6B 的 R@10 为 0.809，高于 bge-base-en-v1.5 的 0.742 和先前发布的 all-MiniLM-L6-v2 的 0.572；在 k=10 时与 bge-base 正面对比，胜负为 +32/−12（p=0.004）。 结果文件：embedder-recall-shootout-20260727.json、 embedder-recall-qwen-vs-bge-20260728.json。

Cortex Console（Web UI）

由守护进程本身提供的运维仪表板——在浏览器中打开 http://127.0.0.1:8765/ui/（/health 和 /mcp 端点 保持不变；控制台是新增功能）。这是一个以只读为主的仪表盘，用于查看和引导人类 原本无法观察的记忆： Observatory（运行状况、各层计数、记忆存储容量表、梦境仪表、整合审核）、Cortex（按实体显示带溯源信息的 规范事实、版本历史链、对有争议的条目执行 Adopt/Discard）、 World / Lessons / Episodes、Stream（支持重新排序/BM25 切换和排序追踪面板的实时搜索）、Recall（多跳遍历，以及两个实体间的路径）、 Graph（实体构成的 3D 星系，每颗星都有对应的实体页面，并提供表格视图）、Review（图谱审核队列：接受/拒绝合并；或者对于源文件及其自身的裸概念 band.py ↔ band，记录 implements 边，而不是强行选择合并或忽略；后台梦境已作出判断的提案会附带判定标签——接受/拒绝/暂缓及置信度，悬停提示中显示模型给出的理由——仅作为线索，而非决定）、Insight（从图谱摘要中提取的枢纽、社区和待解问题），以及 Settings（每个安全的 config.yaml 标量，带有实时生效/重启生效标签、差异预览和原子保存）。指向 v3 之前控制台的书签（#/console、#/atlas、#/coordination）会跳转到相应视图。

Board 是只读的协作视图：活跃成员名单/状态时长、上报的子级、暂停需求/恢复、资源持有者和 FIFO 队列。待处理邮件数量仅对调用方主体可见；最新保留的 100 条发送/读取/确认/唤醒/过期事件不包含任何消息正文。此视图要求在 coordination.allowed_principals 中配置 bearer，即使是在其他方面开放的环回安装中也一样。刷新既不会接收/确认邮件，也不会处理已过期的租约。快照一分钟后会标记为过期；使用 Refresh 获取最新状态。API 为 GET /api/agents?view=coordination&limit=50（成员名单限制为 1–50）；默认的 /api/agents 感知响应保持不变。传入审计的可见性采用当前收件人归属，因此收件人地址被清理后，传入事件可能不再显示；审计保留策略也会限制时间线长度。持久化层未启动时会报告不可用，而不会通过此次读取初始化存储。

Auth 与 /mcp 保持一致：/ui（静态外壳）和 /health 无需认证；设置了 PSEUDOLIFE_MCP_TOKEN 时，/api/* 需要相同的 bearer（控制台会提示输入并在本地保存）。REST POST 请求体按传输字节数限制大小：含文本的写入接口（/api/facts/set、/api/consolidate、/api/supersede）限制为 4 MiB，/api/coordination/* 限制为 32 KiB，会话结束钩子限制为 16 KiB，/api/pair 限制为 1 KiB，其他所有接口限制为 256 KiB；超出限制的请求会返回 HTTP 413 {"error": "request_too_large"}。无需 CDN，完全离线：Svelte 构建产物已提交至 pseudolife_memory/web/static/，其中包含随附的 OFL 字体 和随附的 3D 引擎，由守护进程直接提供，因此守护进程镜像和 pip 安装均不需要 Node。源代码位于 frontend/；CI 会重新构建，并在提交的构建产物不一致时失败。要开发 UI？可通过基于固定数据的开发服务器（无需 Postgres、 无需 torch）使用预置数据查看控制台： python -m pseudolife_memory.web.devserver → http://127.0.0.1:8770/ui/。 其负载会自行标明（/health 中包含 "fixtures": true），顶栏也会显示“演示数据，并非真实存储”标签，因此不会把固定数据运行误认为真实存储。

功能一览

故障排查

先运行 curl http://127.0.0.1:8765/health — 它会报告守护进程的 软件包 version、架构版本、存储后端、身份验证状态和 persist_errors（非零表示 写入操作未能写入 Postgres；请检查 docker logs pseudolife-mcp-daemon）。

• 皮层一直为空（规范事实不会自行出现）。 /health 中的 "extractor": "none" 表示未配置提取器，因此梦境不会写入任何事实，而 memory_fact_set 是唯一的皮层写入工具——这在轻量版中符合预期。将守护进程指向一个兼容 OpenAI 的端点 （快速入门），或使用 Docker 版内置的旁路服务。"extractor": "disabled" 则表示配置中关闭了梦境功能。"extractor": "stalled" 表示已配置提取器，但实时梦境已停止向其发送内容；stall 子对象会给出原因和时间。若 stall.reason 为 login_expired，说明提取器 CLI 的登录已过期（或托管端点拒绝了其密钥）：在守护进程所在主机上重新运行 claude auth login（或 codex login）。请参阅梦境停滞时。
• 轻量版守护进程在 Windows 上因数据路径相关消息而无法启动：内置 Postgres 运行时要求数据目录路径仅包含 ASCII 字符。将 PSEUDOLIFE_MCP_DATA_DIR 设为符合要求的路径（例如 C:\pseudolife-data）—— 配置。
• 首次构建速度慢／体积大。 守护进程映像（约 5.0 GB，构建需数分钟）内置了 CPU 版 torch 和嵌入权重（Qwen3-Embedding-0.6B 加 MiniLM）；提取器旁路服务首次构建时还会下载约 5.3 GB 的模型。之后每次启动都能离线且快速完成——如果重新构建时又在下载模型，说明 Docker 层缓存已被清理。
• 运行 wsl --shutdown 后无法访问守护进程（Windows）：主机端口转发已失效——运行 docker restart pseudolife-mcp-daemon 即可重新建立。
• Docker 占用大量内存（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 中主机侧的端口。
• 控制台显示“离线”／Unauthorized：“离线”表示无法访问守护进程（见上文）；401 提示表示守护进程使用了 PSEUDOLIFE_MCP_TOKEN，请将该令牌粘贴到控制台的 Token 对话框中。
• 编码 Agent 看不到工具：claude mcp list 或 codex mcp list 应显示 pseudolife-memory ✓ 已连接。若没有，请重新检查 URL（http://127.0.0.1:8765/mcp——/mcp 路径很重要）以及设置令牌时使用的 bearer 标头。守护进程启动时会在预热线程中预加载嵌入器（约 5–10 秒）；若首次调用过早，可能与其发生竞争并多花几秒钟。
• 升级后工具消失／客户端日志显示“Connection closed”：已注册的 shim 命令可能位于仓库虚拟环境之外，而 shim 需要 MCP SDK v2——若该环境中的 SDK 版本低于 v2，shim 启动时会崩溃。shim 会检测到此问题，并在 stderr 中打印解释器路径和确切的修复方法：在该解释器中运行 pip install -U "mcp>=2.2,<2.3"，或重新运行安装程序（它会注册项目虚拟环境中的 shim）。
• Claude Desktop 显示“Couldn't start for Cowork and Code sessions. Error: unhandled errors in a TaskGroup (1 sub-exception)”：真正的异常位于应用日志文件夹中的 mcp-server-pseudolife-desktop.log （若条目尚未重命名，则为 mcp-server-pseudolife-memory.log）底部（Windows 上为 %LOCALAPPDATA%\Claude\Logs，macOS 上为 ~/Library/Logs/Claude）。如果是 401，说明守护进程要求提供令牌，而由 Desktop 启动的 shim 没有凭据：Desktop 会清理环境变量，因此请在条目的 env 中设置 PSEUDOLIFE_MCP_TOKEN_FILE（参见接入编码 Agent中的 Claude Desktop），或重新运行 ops/install.* --client claude-desktop，然后彻底退出并重新启动应用。在 Windows Store 版本中，文件位于 %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\ 下。如果条目中已有 PSEUDOLIFE_MCP_TOKEN_FILE，但仍返回 401，则说明 shim 早于令牌文件支持版本（截至 0.15.0 的 PyPI 版本只读取字面令牌）：功能完整的 shim 运行 pseudolife-mcp --help 时会列出 PSEUDOLIFE_MCP_TOKEN_FILE；请升级 shim（在仓库检出目录中运行 python ops/update_clients.py --only shim，它会在正在运行的版本旁安装新的运行时，因此无需关闭会话），然后重新运行安装程序；现在安装程序会拒绝将旧版本注册为使用令牌文件。
• Harness 提示“已移除工具”并不代表服务中断。 恢复的会话记录中可能包含比当前工具集层级提供的更多工具——这只是可见性筛选，并非连接中断。在判断 MCP 是否停机前，先调用一次 memory_search。

卸载

**Lite 版：**移除 MCP 注册（claude mcp remove pseudolife-memory / codex mcp remove pseudolife-memory），然后运行 pip uninstall pseudolife-mcp。如果还想删除记忆库，请删除用户数据目录（Windows 上为 %LOCALAPPDATA%\pseudolife-mcp， Linux 上为 ~/.local/share/pseudolife-mcp，macOS 上为 ~/Library/Application Support/pseudolife-mcp，或者 PSEUDOLIFE_MCP_DATA_DIR 所指向的位置）。请先备份：Lite 版也支持运行 pseudolife-mcp backup。

Docker 版——每一步都需要明确确认删除：

# 1. Optional: take a final backup first (ops/backup.ps1 or ops/backup.sh).
# 2. Stop and remove the containers (volumes survive this).
docker compose -f ops/docker-compose.yml down
# 3. Remove the MCP registration.
claude mcp remove pseudolife-memory
codex mcp remove pseudolife-memory
gemini mcp remove pseudolife-memory -s user
# 4. Only when you're sure: delete the data volumes (THIS is the memory).
docker volume rm pseudolife-mcp-bank pseudolife-mcp-state

主机进程安装：还需注销登录任务 （Unregister-ScheduledTask -TaskName "Pseudolife-MCP Daemon"），并从 ~/.claude/settings.json 和/或 ~/.codex/hooks.json 中移除 SessionStart 简报钩子，以及 UserPromptSubmit 记忆变更钩子 （pseudolife-mcp prompt-hook；旧版安装：discipline echo）。每个被编辑的文件旁边都会有带时间戳的 .bak-* 文件。

测试

运行 pip install -e .[dev]，然后运行 pytest tests/。测试套件涵盖所有层级，从 MemoryService 接口到 Cortex Console REST API； 模型密集型部分使用存根，因此运行快速且无需联网。由 PG 支持的测试套件各自在随附的开发容器中使用每次运行单独创建的临时数据库 pseudolife_memory_test_<pid> （绝不会使用你的真实记忆库；并发运行不会冲突），退出时会删除该数据库；如果没有 Postgres，则会正常跳过。 测试套件使用自己的测试登录凭据，无法打开记忆库（运行 pseudolife-mcp test-login create 会写入 ~/.pseudolife-mcp/test-pg.env； 参见Agent 隔离）；若未创建，则使用 ops/.env 中的密码（可通过 PSEUDOLIFE_TEST_DATABASE_URL 或 PSEUDOLIFE_TEST_PG_PASSWORD 覆盖）。如果服务器可连接但拒绝凭据，PG 测试会报错而不是跳过，因此密码轮换绝不会意外导致测试全绿。完整开发环境设置见：CONTRIBUTING。

尚未实现的功能

• 通过 MCP sampling 进行反思——这会让梦境借助 Claude 本身来进行提取； Claude Code 目前尚不支持。
• 复制 / 离线副本——一个守护进程管理一个记忆库；其他 机器通过网络使用它 （远程记忆库），但目前没有副本或 离线模式。
• 自动摄取世界知识——从实时网络填充世界皮层 需要一个独立服务未附带的网页获取工具；目前，有网络访问权限的 Agent 可以通过 memory_world_set 自动完成获取和引用步骤。

支持

**由个人维护，尽力而为。**此项目由一人构建、测试和运行； 没有支持合同，也不承诺响应时间。尽管如此，我们会阅读问题，且大多数都会得到回复。

• 遇到故障 → 提交 错误报告。 表单会要求提供 /health 输出、架构版本、安装层级 和客户端，因为这四项通常就能在来回沟通之前解答大多数问题。
• 缺少某项功能 → 提交 功能请求。 请说明你想完成什么，而不只是想添加什么。
• 发现安全问题 → 请勿提交公开问题。请通过 GitHub 的 私有漏洞报告渠道提交——见 SECURITY.md。有关记忆 完整性：参见安全态势。
• 提交补丁 → 请参阅 CONTRIBUTING 和 CODE_OF_CONDUCT。标准是“精准、经过测试并且 说明清楚”，而不是“规模庞大”。

如果你需要有人可以联系，对比——适合改用其他方案的情况列出了提供支持服务的供应商。

许可证

Apache-2.0——参见 LICENSE 和 NOTICE。