Palace

为编码 Agent 打造的本地优先记忆。
让 Agent 在不同会话之间记住决策、修复、命令和偏好。
一个二进制文件、一个 SQLite 文件、无需 API 密钥、无需云服务。

快速开始 · 安装 · 工作原理 · 客户端 · 命令行 · MCP 工具 · 常见问题

Palace 为 Claude Code、Codex、Cursor、Gemini CLI、VS Code、OpenCode、 Cline、Zed、Goose、Windsurf 和 Claude Desktop 提供记忆，让记忆 在不同会话之间延续。它会原样存储发生过的内容，在相关时自动回忆， 并标明每个答案的来源。

You:    why did we switch the queue to SQLite last month?
Agent:  [palace_search → wing my_api, room decisions, filed 2026-09-03]
        You dropped Redis because the deploy target had no persistent volume.
        The benchmark you ran is in the same drawer.

🧭 为什么选择 Palace

每次新的 Agent 会话都从零开始。你得再次解释架构。 Agent 会重复上周被你否决的修复方案。它会搜索整个代码仓库， 重新发现几个月前定下的约定。

Palace 通过以下方式解决这些问题：

• 原样存储文本。 代码、笔记和对话会按原文存储，而不是存成会丢失细节的大模型摘要。
• 在本地运行。 嵌入向量由 ONNX Runtime 在你的 CPU 上通过 all-MiniLM-L6-v2（或其他支持的模型）生成。除非启用远程模式，否则任何内容都不会离开你的设备。
• 自动回忆，无需请求。 钩子会在会话开始、你发送提示词时，以及 Agent 调查问题期间注入相关记忆。Agent 无需记得主动搜索。
• 标注来源。 每条结果都会附带其侧翼、房间、源文件、抽屉 ID 和分数明细，方便你核实答案的来源。
• 以单个二进制文件交付。 无需 Python、向量数据库或 Docker。只需一个 palace 可执行文件和一个 palace.db 文件。

它也适用于软件项目之外的场景。creative 和 personal 配置可适配世界观构建、小说创作、辅导或家庭笔记。

📦 安装

任选一种方式。每种方式都会安装 palace 二进制文件。之后运行 palace install 以连接你的 Agent。

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/AncientiCe/palace-rs/main/scripts/install.sh | sh

Windows（PowerShell）

irm https://raw.githubusercontent.com/AncientiCe/palace-rs/main/scripts/install.ps1 | iex

这些脚本会下载匹配的 GitHub Release 二进制文件、验证其 SHA-256 校验和，并完成安装。之后要升级时，再次运行相同的命令即可。

Homebrew（macOS Apple Silicon / Linux）

brew tap AncientiCe/palace
brew install palace

升级时，请先刷新 tap。如果不运行 brew update，Homebrew 可能会一直 报告旧版本已安装：

brew update && brew upgrade palace

当某个版本发布更新了记忆协议规则（CHANGELOG 会说明），之后请再次运行 palace install，以便你的 Agent 获取新的规则文本。

MCP 注册表 / MCPB 捆绑包。 Palace 已在官方 MCP 注册表 中列出，名称为 io.github.ancientice/palace-rs。每次发布还会提供一个 palace-<version>.mcpb 捆绑包（Linux x86_64、macOS arm64、Windows x86_64），可在 Claude Desktop 等 兼容 MCPB 的宿主中一键安装。

从源代码构建

git clone https://github.com/AncientiCe/palace-rs && cd palace-rs
cargo build --release   # binary at target/release/palace

嵌入模型（约 90 MB）会在你首次挖掘或搜索时从 Hugging Face 下载，之后 会缓存在 ~/.cache/huggingface 中。

⚡ 快速开始

palace install            # connect every supported agent on this machine
palace doctor             # check that every client is wired up
palace init ~/my-project --yes --auto-mine   # detect rooms, write palace.yaml, mine

重启你的 Agent 应用，使其重新加载 MCP 配置。然后试着询问：

“我们对这个项目如何处理数据库迁移有哪些了解？”

Agent 应调用 palace_search，并根据记忆作答，同时注明所用的抽屉。你也可以在终端中搜索：

palace search "how did we decide on the database schema"

之后，Agent 会在完成重要工作后写下一篇日记条目，并将持久有效的决策保存为事实。明天，无论使用哪个 Agent，都能从今天的进度继续工作。

🔍 工作原理

宫殿

记忆按建筑的结构组织，让搜索更聚焦：

_{图 1。一座宫殿包含多个翼区。房间对抽屉进行分组，知识图谱和日记则与它们并列。}

翼区分为项目翼区（磁盘上的文件夹，由 palace mine 创建）和主题翼区（没有文件夹，例如聊天记录或会议笔记，由 palace_create_wing 创建）。

检索

flowchart LR
    Q["💬 Question<br/>from you or the agent"] --> S["Sanitize<br/>strip pasted dumps"]
    S --> I["Classify intent<br/>decision · how_to · preference …"]
    I --> H["Hybrid search<br/>BM25 + cosine"]
    H --> B["Coding boosts<br/>+ preference pass"]
    B --> R{"Rerank?<br/>optional"}
    R --> OUT["📎 Results<br/>scores + source + neighbours"]
    DB[("palace.db<br/>local embeddings")] -.-> H

_{图 2。查询的处理过程。所有操作都在本地 CPU 上运行。}

搜索会将 BM25 关键词评分与基于本地嵌入向量的余弦相似度结合起来，然后针对编码问题应用意图加权。每个查询都会被分类为 preference、decision、how_to、definition、temporal 或 unknown。偏好类问题（“我喜欢怎样写提交信息？”）会针对带有偏好标签的文本片段进行专门检索。本地交叉编码器重排器可作为选项使用（--rerank 或 PALACE_RERANK=1）。

嵌入模型

Palace 内置了 all-MiniLM-L6-v2，并且可以将 Palace 切换到另一个本地模型。所有向量都会根据已存储的文本重新构建，因此切换不会丢失记忆。

实验性模型在编码 Agent 评测中的得分低于 MiniLM，但在真实 Palace 的探测测试中得分更高（参见基准测试）。你可以在自己的 Palace 上试用：是否切换由验证结果决定。

palace embeddings list                       # models, which is active, which are downloaded
palace embeddings estimate minilm-l6-v2-q8   # time, disk and latency, measured on this machine
palace embeddings migrate minilm-l6-v2-q8    # build, verify, switch
palace embeddings rollback                   # back to the previous model, instantly
palace embeddings cleanup                    # drop the previous model's vectors

migrate 会分批构建新向量，同时搜索仍使用当前模型，因此可以安全地中断并重新运行。向量构建完成后，它会使用从你的 Palace 中选取的 200 个已知项探测，对比新模型和当前模型（混合与纯向量召回率 @1/@5，以及查询延迟）。只有当召回率 @5 的下降不超过 0.01，且 p95 查询延迟在预算范围内时，才会切换。预算为当前模型 p95 的两倍，且至少为 25 ms。运行 palace embeddings cutover --force 可强制切换，或运行 palace embeddings cancel 保留当前模型。

在 config.json 中设置 embedding_model（或设置 PALACE_EMBEDDING_MODEL）可为新的空 Palace 选择模型。现有 Palace 不会自行切换。palace status、palace_status 和 palace_session_context 会报告待处理的迁移，直到你运行 migrate。迁移不会自行发生：你需要运行 migrate，或让你的 Agent 运行它；这会使用 palace_embeddings MCP 工具（它会在服务后台执行相同步骤）。在远程模式下，模型由服务端管理，因此这些命令会在服务端运行。

检索前会清理 Agent 生成的查询转储。返回结果会附带分数来源（combined、cosine、bm25、coding_boost、preference_match、rerank_score、intent）以及来自同一源文件的相邻分块。

自动回忆（钩子）

palace install 会注册用户级钩子，因此记忆可在每个项目中生效，无需编辑各项目的文件：

_{图 3。三个钩子将记忆读入会话。第四个钩子确保会话中的经验教训被写回。}

自动回忆仅限当前项目。其他项目翼中的抽屉和其他项目的日记不会显示。主题翼仍会显示。

所有钩子都以开放失败方式运行：如果 palace 缺失或为空，Agent 会照常工作。

记忆协议

palace install 还会在每个客户端的指令文件中写入一条简短规则，告诉 Agent 何时使用记忆：

1. 会话开始： palace_status → palace_session_context → palace_diary_search。
2. 回答有关过去的决策、偏好或历史的问题之前： 在 grep 之前先运行 palace_search 和 palace_kg_query。
3. 工作完成后： 运行 palace_diary_write，并使用 palace_kg_add 添加持久事实。

对于当前符号、精确定义，以及可能在提取后发生变化的代码，grep 仍然是首选工具。

九个协议工具都标记为 _meta."anthropic/alwaysLoad" = true，因此 Claude Code 2.1.121 及更高版本会保持这些工具加载，而不是将其延后到工具搜索时再加载。

记忆层

palace wake-up 会打印 L0 和 L1。Agent 通过 MCP 工具访问 L2 和 L3。

🔌 支持的客户端

默认情况下，palace install 会为所有受支持的客户端配置 （--client all）。只有在 Gemini CLI、VS Code、Windsurf、OpenCode、Cline、Zed 和 Goose 的配置文件夹存在时，才会将它们纳入配置，因此 Palace 不会设置你没有安装的 Agent。使用 --client <name> 可显式配置一个客户端。

规则文件以托管区块的形式写入。现有内容会保留。

palace install --client claude                       # one client only
palace install --scope project --path ./my-project   # project-level rule files
palace install --no-rule                             # MCP wiring only, no rule
palace install --dry-run                             # preview the changes
palace uninstall                                     # undo everything

使用 --scope project 时，规则会写入 <project>/CLAUDE.md、<project>/AGENTS.md （Codex、OpenCode、Cline、Zed 和 Goose）、<project>/GEMINI.md、<project>/.github/copilot-instructions.md、 <project>/.windsurf/rules/palace.md 和 <project>/.cursor/rules/palace.mdc。 Cursor、VS Code 和 OpenCode 还会获得项目级 MCP 配置 （.cursor/mcp.json、.vscode/mcp.json、opencode.json）。

{
  "mcpServers": {
    "palace": { "command": "palace", "args": ["mcp"] }
  }
}

[mcp_servers.palace]
command = "palace"
args = ["mcp"]

claude mcp add palace -- palace mcp

MCP 提示词

Claude Desktop 无法运行钩子，因此服务会在提示词选择器中提供两个提示词：

配置方案

配置方案会更改 Agent 规则、协议文本，以及 palace init 查找的房间：

palace install --profile creative

配置方案会保存到 ~/.palace/config.json。设置 PALACE_PROFILE 可对单个进程覆盖此配置。

远程模式（共享团队记忆）

默认情况下，palace mcp 为你的本地 Palace 提供服务。远程模式会将其转为 stdio-to-HTTP 桥接，连接到共享的 Palace Server， 即面向团队的商业版可自托管服务。客户端注册方式无需更改。

palace remote set --endpoint https://palace.yourco.com   # prompts for the ps_… API key
palace remote on
palace remote test      # runs the MCP handshake and reports the tool count
palace remote status    # mode, endpoint, masked key
palace local            # back to the local palace

🧰 CLI 参考

运行 palace <command> --help 查看所有标志。

设置

添加记忆

查找记忆

维护

服务

挖掘项目

flowchart LR
    DIR["📁 Your repo"] --> F["Filter<br/>.gitignore + skip build dirs"]
    F --> C{"Changed since<br/>last mine?"}
    C -- no --> SKIP["Skip"]
    C -- yes --> CH["Chunk + pick room<br/>using palace.yaml"]
    CH --> E["Embed locally<br/>all-MiniLM-L6-v2"]
    E --> DB[("palace.db")]

_{图 4．挖掘只会处理已更改的文件，因此重复运行的成本很低。}

palace mine 会遵循 .gitignore，并跳过 .git、node_modules、 target、build、dist、vendor 等构建输出目录。它会读取常见的 文本和源代码格式：md、txt、rs、py、js、ts、tsx、go、 java、rb、sh、sql、json、yaml、toml、html、css、csv 等。

palace mine ~/my-project \
  --wing my_project            # override the wing name
  --limit 100                  # process at most 100 new or changed files
  --dry-run                    # preview without storing
  --no-gitignore               # ignore .gitignore rules
  --include vendor,third_party # force-include these paths

--limit 运行可以续接：下一次运行会从上次停止的位置继续。

使用 palace gain 衡量价值

palace gain                       # last 30 days
palace gain --project my_project --since 7d
palace gain --history             # recent tool calls
palace gain --json
palace gain --record <query_id> <drawer_id> useful   # or not_useful / wrong_answer

palace gain - last 30d (my_project)
  Tool calls         : 412   (sessions: 27)
  Hit rate           : 88%   (search hits 142/162)
  Precision@1        : 92%
  Precision@5        : 95%
  Tokens saved (est) : ~78,400
  Re-index skipped   : 31    (duplicate drawers avoided)
  KG facts recalled  : 56
  Diary recalls      : 8
  Repeat Qs avoided  : 19
  p95 latency        : 41 ms

使用情况元数据会保留在你的本地 palace.db 中。设置 PALACE_GAIN_DISABLED=1 即可关闭记录。

🧩 MCP 工具

🔧 配置

设置的加载顺序为：环境变量，然后是 ~/.palace/config.json，最后是默认值。

config.json 使用相同设置作为键：palace_path、profile、 entity_languages、topic_wings、people_map、mcp_mode、 remote_endpoint、remote_api_key、embedding_model、 embedding_latency_budget_ms。Palace 会以仅所有者可读写的 0600 权限写入此文件。

palace.yaml（每个项目）

palace init 会创建此文件。编辑它可以调整文件到房间的映射方式：

wing: my_project
rooms:
  - name: backend
    description: Server and API code
    keywords: [api, server, routes, models]
  - name: frontend
    description: UI components
    keywords: [ui, components, pages, views]
  - name: general
    description: Everything else
    keywords: []

📊 基准测试

编码 Agent 记忆评测

一组模拟真实项目记忆的夹具（决策、过去的故障、命令、惯例、 偏好、当前方向），包含 51 个问题，例如：

• 我们为什么选择捆绑式 sqlite？
• 上次我们如何修复迁移测试失败的问题？
• 我应该运行什么 clippy 命令？

cargo test --test coding_agent_eval -- --nocapture

测试会报告 recall@1 和 recall@5，并在检索结果低于固定阈值时失败。它回答了一个重要问题：编码 Agent 需要时，能否找到正确的项目上下文？

此评测有一部分是经过有意调优的。 排序器针对编码 Agent 的增强包含了少量取自评测问题本身的短语（例如 “explain themselves”、“proof priority” 和 “release theme”），因此此处和下方 bake-off 中的调优分数高于仅使用通用排序时的分数。我们会保留这些短语，直到通用改进达到相同分数，然后再将其移除。在移除这些短语后，使用相同代码测得的结果如下：

这些短语不会影响此评测之外的结果：真实 palace 探测和每个会话的 LongMemEval 排序，在使用和不使用这些短语时完全相同。

嵌入模型对比测试

tests/embedding_bakeoff.rs 使用嵌入式抽屉，对此评测中的所有嵌入模型进行评分，并使用来自真实 Palace 的 200 个已知条目探测进行测试。它还会测量索引吞吐量和查询延迟。每个探测都是抽屉中的一个内部句子，约有 30% 的词被删去。

PALACE_RUN_BAKEOFF=1 PALACE_BAKEOFF_DB=~/.palace/palace/palace.db \
  cargo test --release --test embedding_bakeoff -- --nocapture

混合召回率：从一个包含 10,700 个抽屉的 Palace 中抽取 400 个抽屉；Windows，16 个线程。BGE 的排名最佳，采用 0.5 的余弦下限以及余弦/BM25 各占一半的权重；其注册表条目中已包含这些设置。只有在编码 Agent 评测中达到 MiniLM 的表现，模型才会以非实验性模型的身份发布。因此，尽管 BGE 模型在真实 Palace 探测中表现更佳，目前仍处于实验阶段。verify 会在切换前用你自己的 Palace 测量同一指标。

LongMemEval

LongMemEval s_cleaned 上的检索召回率：评估了 470 个问题，每个问题对应一个约 50 个会话、115k 个 token 的干扰内容集合。按照惯例，不计入 30 个弃答问题。

对话轮次对这一行体现了 Palace 实际存储对话的方式：每个会话都会经过与 palace mine-convos 相同的标准化器和分块器（每个用户轮次及其回复组成一个块），会话排名取其最佳块。每会话行采用 LongMemEval 常用的粒度，便于与其他系统比较。

🔒 隐私与数据

• 默认情况下，所有数据都存储在本地。 一个 SQLite 文件位于 ~/.palace/palace/palace.db。嵌入向量由你的 CPU 计算。
• 网络访问仅用于从 Hugging Face 一次性下载模型，以及在开启远程模式时访问你自己的 Palace Server。
• 不收集遥测数据。 palace gain 统计信息只会写入你的本地 数据库。
• 使用 palace export 备份，或复制 palace.db。
• 使用 palace_forget 删除单条记忆，或删除 ~/.palace 以清除所有内容。

Palace 会存储你挖掘的所有内容。在挖掘代码库之前，使用 .gitignore 排除机密信息。

🩺 故障排除

❓ 常见问题

📚 将 Palace 用作库

Palace 也是一个 Rust crate（palace）。将它添加为 git 依赖项：

[dependencies]
palace-rs = { git = "https://github.com/AncientiCe/palace-rs", default-features = false }

use palace::{db, knowledge_graph, store};

let conn = db::open_in_memory()?;
store::add_drawer(&conn, "wing_code", "backend",
    "We use SQLite with WAL mode for concurrent reads.",
    None, "architecture.md", 0, "example", 4.0)?;
knowledge_graph::add_triple(&conn, "Palace", "stores_data_in", "SQLite",
    Some("2026-04-01"), None, 1.0, None, None)?;

default-features = false 会省去 CLI 依赖项。完整示例请参阅 examples/basic_usage.rs（cargo run --example basic_usage）。palace::palace::Palace::search_with_provenance 会返回与 MCP 工具相同的分数详情。

🧪 开发

cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
cargo audit

测试使用内存中的 SQLite，只有需要嵌入模型的测试才会加载该模型。请参阅 CONTRIBUTING.md、SECURITY.md 和 CHANGELOG.md。

🚚 从旧版本迁移

palace init ~/my-project --yes --auto-mine
palace mine-convos ~/Desktop/transcripts
palace status

📜 许可证

MIT