MemPalace 配置完全指南：从全局 config.json 到多后端向量存储与身份层

MemPalace 的配置体系分为三层：用户级全局配置（~/.mempalace/config.json）、项目级配置（mempalace.yaml 与 entities.json）、以及独立的身份文件（identity.txt）。本文基于仓库内的 configuration.md 指南展开，并对照 config.py、cli.py、miner.py、layers.py 等源码实现，系统讲解每个配置项的含义、默认值与底层生效机制。读完你将掌握：如何为多台机器/多个团队项目定制记忆宫殿路径与集合名、如何在 ChromaDB / SQLite / Milvus / Qdrant / pgvector 之间切换存储后端、如何通过 mempalace init 生成并维护项目级配置，以及如何用 identity.txt 定义 AI 的“第 0 层自我认知”。

配置优先级总览

MemPalace 的配置读取遵循 环境变量 > 配置文件 > 内置默认值 的整体优先级（见 config.py 顶部模块注释），每个配置项在解析时会先查环境变量，再查 ~/.mempalace/config.json，最后落到模块级常量默认值（例如 DEFAULT_PALACE_PATH、DEFAULT_COLLECTION_NAME、DEFAULT_BACKEND、DEFAULT_MAX_BACKUPS 均定义在 config.py 的 225–240 行附近）。

需要特别留意的是个别属性的具体解析顺序与“宏观口号”不完全一致，一切以源码为准。例如 backend 属性在 config.py 中的实际顺序是：config.json 中的 "backend" 字段 → 环境变量 MEMPALACE_BACKEND → 兜底 "chroma"；而连接型变量（如 qdrant_url、milvus_uri、pgvector_dsn）则普遍是 环境变量优先于 config.json。这意味着：全新安装的 config.json 中不包含 backend 键，此时 MEMPALACE_BACKEND 环境变量可以正常生效；但一旦在 config.json 中显式写入了 "backend"，它就优先于同名环境变量。命令行层面的 --backend <name> / --palace <path> 则是在所有文件与环境解析之上的“本次命令级”覆盖。

全仓库涉及的配置文件位置如下：

文件	作用域	说明
~/.mempalace/config.json	用户全局	核心设置（palace 路径、后端、人名映射、保留策略等）
~/.mempalace/people_map.json	用户全局	人员名规范映射，读取时优先于 config.json 内联的 people_map
~/.mempalace/identity.txt	用户全局	纯文本身份描述，作为唤醒时的 L0 层加载
<project>/mempalace.yaml	项目级	wing、rooms、palace_path 覆盖、exclude_patterns 等
<project>/entities.json	项目级	实体审计记录，mempalace init 检测并合并到全局注册表
<palace>/<backend>_backend.json	palace 级	后端标记文件，防止对错误的服务器静默打开 palace

其中 config.json、identity.txt、people_map.json 均位于 ~/.mempalace/ 配置目录（源码中由 MempalaceConfig._config_dir 计算，默认即 ~/.mempalace，见 config.py）。

全局配置 ~/.mempalace/config.json

最小可用示例与核心键

configuration.md 给出的全局配置 JSON 示例如下：

{
  "palace_path": "/custom/path/to/palace",
  "collection_name": "mempalace_drawers",
  "people_map": {"Kai": "KAI", "Priya": "PRI"},
  "max_backups": 10
}

各键含义与默认值：

Key	Default	说明
palace_path	~/.mempalace/palace	默认本地 palace 存储抽屉（drawers）的位置
collection_name	mempalace_drawers	默认后端集合（collection）名
people_map	{}	实体名称 → AAAK 编码映射，用于人名归一化
max_backups	10	保留的带时间戳 palace 备份数量，超出后最旧的先被清理。作用于 mempalace migrate（产物形如 <palace>.pre-migrate.*）与 mempalace repair max-seq-id（产物形如 chroma.sqlite3.max-seq-id-backup-*），这两条命令每次运行都会写一份完整副本。设为 0 表示保留所有备份（例如由外部保留策略统一管理清理）

palace_path：默认 palace 在哪

默认值为 ~/.mempalace/palace。源码中该键的解析链路（config.py）为：显式构造参数 palace_path > 环境变量 MEMPALACE_PALACE_PATH（兼容旧名 MEMPAL_PALACE_PATH）> config.json 的 palace_path > DEFAULT_PALACE_PATH。环境变量路径会先做 expanduser 展开与 abspath 规范化，避免出现未解析的 ~ 或 .. 片段导致的“意外跳转”（与 CLI --palace 走同一套归一化逻辑）。

值得注意的衍生路径：tunnel_file 与 hallway_file 并不是 palace 内部文件，而是 palace_path 的兄弟文件（tunnels.json、hallways.json），这样跨 wing 的走廊/隧道状态就能跟随“当前配置的 palace”而不是被写死在全局目录（见 config.py）。

collection_name：抽屉集合名

默认 mempalace_drawers，通过 get_configured_collection_name() 被各模块缓存读取（lru_cache 避免反复读盘）。多数用户无需修改；只有当同一份配置目录需要区分多套存储时才需要调整。

people_map 与人名归一化

people_map 用于把同一人的不同拼写/昵称归一成统一的规范名（文档中的示例为 {"Kai": "KAI", "Priya": "PRI"}）。从源码看，运行时首先尝试读取独立的 ~/.mempalace/people_map.json（config.py），只有在该文件不存在或解析失败时才回退到 config.json 内联的 people_map。save_people_map() 在写入时使用原子写 JSON（临时文件 + rename + 目录 fsync），文件权限被限制为 0600，因为这份映射带有个人信息（config.py）。

max_backups：迁移/修复备份保留策略

文档明确指出 max_backups 作用于两类每次都会写整库副本的命令：mempalace migrate 和 mempalace repair max-seq-id。源码（config.py）显示其解析顺序为 MEMPALACE_MAX_BACKUPS 环境变量 > config.json 的 max_backups > 默认 10；0 表示禁用清理；负数或非数值会静默回退到默认值而不会让 migrate/repair 崩溃。这对于“定时跑迁移/修复的机器”很重要——没有保留策略时备份集会无限增长直至占满磁盘。

源码支持的更多全局键（进阶）

除了文档表格中的 4 个键，config.py 还读取一批全局键。它们或由 onboarding/init 写入，或供高级调优使用，归纳如下（均需在 config.json 顶层或相应子对象中填写）：

键	默认值	作用与约束（源码依据）
chunk_size	800	每个抽屉块（chunk）的字符数，需 >= 1
chunk_overlap	100	相邻块重叠字符数，校验约束为 0 <= overlap <= chunk_size // 2，过大可能使短行内容上的分块循环永不前进（issue #2056）
min_chunk_size	50	小于此长度的块不归档，校验约束 <= chunk_size，否则将“零抽屉产出”
topic_wings	7 个内置主题（emotions/consciousness/memory/technical/identity/family/creative）	主题 wing 名称列表，影响对话/内容归类
hall_keywords	内置每主题关键词表	大厅（hall）到关键词的映射
embedding_model	老 palace 回退 minilm	minilm / embeddinggemma / openai-compat；切换模型意味着更换向量空间，需重嵌入
embedding_device	auto	auto/cpu/cuda/coreml/dml，auto 运行时探测可用加速器
embedding_threads	auto（逻辑核数一半）	ONNX Runtime intra-op 线程数上限；0/负数 = 不设上限
hooks	{"auto_save": true, ...}	auto_save、silent_save、desktop_toast、daemon 等钩子行为开关
lang	无	显式主语言码（MEMPALACE_LANG 环境变量优先），影响本地化输出与排序打分
entity_languages	["en"]	实体检测启用的语言列表，可经 MEMPALACE_ENTITY_LANGUAGES 逗号分隔覆盖
topic_tunnel_min_count	1	创建跨 wing 隧道所需的最少共享主题数，调高可减少“Python/Docker/Git”这类公共标签造成的过度连通

以上键的解析与防御性校验都实现在 MempalaceConfig 属性中——例如 _coerce_config_int 对手工编辑出的字符串、布尔值、负数、JSON null 一律静默回退到文档默认值，避免一个手误拖垮 ingest（config.py）。

config.json 的写入安全机制

从源码可以确认，config.json 并非“随手一写”的文件：MempalaceConfig 会对配置目录设置 0700、对配置文件设置 0600 权限；写入走临时文件 + os.replace + 目录 fsync 的原子路径；若文件存在但无法解析（半截写入或手改丢括号），首次 setter 会把它改名保留（.unreadable-<时间戳>-*）再写新文件；若文件存在但根本读不了（权限位错误等），setter 会拒绝覆盖而不是用默认值静默覆盖用户数据（config.py）。这些机制共同保证了“配置永不丢”。

存储后端（Storage Backends）

ChromaDB 是默认后端，开箱即用、无需任何配置。MemPalace 同时提供一套可插拔的后端契约，并刻意在差异极大的存储基质上测试（内嵌存储、本地精确余弦存储、REST 存储、SQL/JSONB 存储），确保契约不会被单一厂商的 API 绑架。所有非默认后端均为显式选择（opt-in）。

后端矩阵

Backend	Mode	Install	Namespaces	Lexical	配置方式
chroma (默认)	Local (embedded)	内置	–	✓	–
sqlite_exact	Local (exact)	内置	–	✓	–
milvus	Local (Lite) · Server opt-in	mempalace[milvus]	✓	✓	MEMPALACE_MILVUS_URI
qdrant	Server (REST)	内置	✓	✓	MEMPALACE_QDRANT_URL
pgvector	Server (Postgres)	mempalace[pgvector]	✓	✓	MEMPALACE_PGVECTOR_DSN

后端的注册通过打包入口点（entry point）机制实现，核心模块把 5 个后端类注册在 mempalace.backends 分组下（见 pyproject.toml）：chroma/milvus/pgvector/qdrant/sqlite_exact 分别对应 backends/ 下的 ChromaBackend、MilvusBackend、PgVectorBackend、QdrantBackend、SQLiteExactBackend。--backend 选择到的类名会先经过 backends/registry.py 的合法性解析再被持久化。

如何选择后端

在任何 mempalace / mempalace-mcp 命令上加 --backend <name>，或通过环境变量 MEMPALACE_BACKEND=<name>，或在 config.json 中写 "backend": "<name>"。CLI 侧，cli.py 将 --palace 与 --backend 定义为全局参数，任何子命令均可携带；init 子命令还有自己的 --backend 用于把后端选择持久化到该 palace。

重要隐私提示：当服务器模式后端指向非自有或非受信自托管服务时，MemPalace 会把抽屉的逐字文本与元数据发送并存储到该服务。这是明确、深思熟虑的后端选择——绝不是默认行为。默认 Chroma 后端完全本地，数据不出机器。

租户隔离与后端标记文件

服务器模式后端（Milvus/Qdrant/pgvector）通过命名空间（namespace）隔离租户，并在 palace 目录写入本地标记文件 <backend>_backend.json，防止“不知不觉地对着错误的服务器打开 palace”（例如本地 palace 本应用 Chroma，却因环境变量残留而连上了远端 Qdrant）。命名空间配置键分别是 MEMPALACE_MILVUS_NAMESPACE、MEMPALACE_QDRANT_NAMESPACE、MEMPALACE_PGVECTOR_NAMESPACE。

ChromaDB（默认，零配置）

本地内嵌、无需运行任何服务。抽屉直接存储在 palace_path 目录内，没有任何连接参数需要配置。选择 Chroma 即使用项目默认值，仓库默认依赖即 chromadb>=1.5.4,<2（见 pyproject.toml）。

SQLite exact（精确向量基准）

本地内置、无需额外安装。它对每一行执行精确余弦计算，不做 ANN 近似索引，因此是精确向量正确性校验与小型 palace 的参照实现。选择方式为 --backend sqlite_exact，没有连接参数。在“结果必须精确可复现”的测试与基准场景中，它常被用来作为与 ANN 后端对照的 ground truth。

Milvus（Lite / Server / Zilliz Cloud）

Milvus 后端基于 pymilvus。安装可选驱动：

pip install mempalace[milvus]

当 MEMPALACE_MILVUS_URI 未设置时，MemPalace 使用每个 palace 独立的 Milvus Lite，数据文件位于 <palace>/milvus.db；设置一个服务器或 Zilliz Cloud URI 则可改用共享的 Milvus 部署。可选依赖声明见 pyproject.toml。

Variable	Default	说明
MEMPALACE_MILVUS_URI	per-palace Milvus Lite	Milvus server / Zilliz Cloud URI
MEMPALACE_MILVUS_TOKEN	(none)	Milvus server / Zilliz Cloud 的 Token
MEMPALACE_MILVUS_DB_NAME	(none)	可选 Milvus 数据库名
MEMPALACE_MILVUS_NAMESPACE	(none)	集合命名空间前缀（租户隔离）
MEMPALACE_MILVUS_CONSISTENCY_LEVEL	Strong	Milvus 一致性级别（Strong、Session、Bounded、Eventually）

一致性级别的取值校验在源码中通过 normalize_milvus_consistency_level() 实现（大小写不敏感，非法值会直接抛错，见 config.py）。

Qdrant（REST，免驱动）

Qdrant 是一个联网 REST 后端。无需安装任何 Python 驱动——客户端直接使用 Python 标准库发起 HTTP 请求，因此你只需要一个自己可控的 Qdrant 实例。该实现位于 backends/qdrant.py。

Variable	Default	说明
MEMPALACE_QDRANT_URL	http://localhost:6333	Qdrant REST endpoint
MEMPALACE_QDRANT_API_KEY	(none)	设置后作为 api-key 请求头发送
MEMPALACE_QDRANT_NAMESPACE	(none)	集合命名空间前缀（租户隔离）
MEMPALACE_QDRANT_TIMEOUT	10.0	REST 请求超时（秒）

默认 URL 刻意指向 localhost：选择 Qdrant 时不会静默把记忆发到远端；只有当你显式配置 LAN/云端 endpoint 时流量才外发（见 config.py 的注释）。超时值经过数值防御：非正数或非数值一律回退到 10.0。

Postgres + pgvector（SQL/JSONB）

一个联网的 SQL/JSONB 后端。安装驱动：

pip install mempalace[pgvector]

服务端需具备 vector 扩展（驱动声明 psycopg[binary]>=3.1，见 pyproject.toml）。

Variable	Default	说明
MEMPALACE_PGVECTOR_DSN	postgresql://localhost:5432/mempalace	Postgres 连接串
MEMPALACE_PGVECTOR_NAMESPACE	(none)	Schema 命名空间（租户隔离）

同样地，默认 DSN 指向 localhost，避免未配置就外连。

把服务端后端放到 MCP 之后

如果要把某个服务器模式后端部署成“团队共享记忆”，可参考 远程/团队服务器指南：一台主机持有 palace、负责 embedding（可选 GPU），并通过 HTTP 提供 MCP 服务；团队成员的 AI 读写同一份共享记忆。该指南提供了 mempalace serve --host 0.0.0.0 --port 8765 --backend milvus 等一键命令与 Qdrant Docker、TLS、只读模式的完整部署步骤。

项目配置（Project Config）

项目级配置由 mempalace init 在你的项目目录中生成。

mempalace.yaml

init 会在项目根目录写一个 mempalace.yaml（示例来自文档）：

wing: myproject
rooms:
  - backend
  - frontend
  - decisions
palace_path: ~/.mempalace/palace

• wing：该项目归入的 wing（羽翼）名，多个仓库可共享同一 wing 以共享记忆；
• rooms：项目内的房间清单，最简单的形式是一组名字字符串；
• palace_path：该项目级覆盖的 palace 路径。

从源码 miner.py 可以补充两个重要细节：

1. 读取顺序与兜底：miner 的 load_config() 读取 <project>/mempalace.yaml；若不存在，会回退到旧名 mempal.yaml；两者都没有时，则使用自动探测默认值——以项目目录名规范化后的 slug 作为 wing，rooms 为 general，并打印提示（目录同名即共享 wing，需要 mempalace.yaml 来消歧）。目录名会经过 normalize_wing_name()（小写化、空格与连字符折叠为下划线），确保与 init/隧道记录用的 slug 一致。
2. rooms 的富形态与排除规则：rooms 的每个元素既可以是字符串，也可以是带 name/description/keywords 的字典——关键词参与文件→房间的路由打分（_tokens 按分隔符切词，避免 views 误中 interviews 这类子串误判）。同时 mempalace.yaml 还支持顶层 exclude_patterns 列表（gitignore 语法），被 scan_project() 直接使用，用于排除日志、构建产物等不希望入库的路径（miner.py）。

本地房间检测器会把目录结构自动转写成这一 YAML：每个检测到的目录成为一个 room，配套生成 description 与 keywords，见 room_detector_local.py。

entities.json

{
  "Kai": "KAI",
  "Priya": "PRI"
}

这是 mempalace init 保存到 <project>/entities.json 的审计记录。源码显示 init 的流程是：先做实体检测（人名/项目/主题），经用户确认后同时写两份——项目内 entities.json（可人工检查/手改）+ 合并进 miner 在挖掘时读取的全局注册表 ~/.mempalace/known_entities.json，后者按 wing 记录 topics_by_wing，供后续计算跨 wing 主题隧道（cli.py）。因此 entities.json 既是可审计的工程产物，也是把“确认过的人/项目/主题”沉淀进全局知识的手段。

init 结束时还会把这两个项目文件加入 .gitignore，防止把含个人实体的审计文件误提交进仓库（cli.py）。

wing 的自动检测来源

mempalace init 期间 wing 按以下来源自动检测：

• 目录名 → 项目 wing（project wings）
• 文件内容中检测到的人 → 人员 wing（person wings）
• mine 命令上的显式 --wing 标志

身份层 Identity（L0 唤醒层）

位于 ~/.mempalace/identity.txt，纯文本，作为Layer 0——每次会话唤醒都会加载：

I am Atlas, a personal AI assistant for Alice.
Traits: warm, direct, remembers everything.
People: Alice (creator), Bob (Alice's partner).
Project: A journaling app that helps people process emotions.

技巧提示：请以 AI 的第一人称视角来书写身份文件。唤醒时这份文本会成为 AI 的自我认知。

源码实现位于 layers.py：Layer0 读取 identity.txt（~ 展开为家目录），缺失时返回一段“No identity configured. Create ~/.mempalace/identity.txt”的引导文本而不是报错；token_estimate() 按约 4 字符/token 估算其上下文占用（约 100 token 量级），保证它常驻提示而不臃肿。后续的 L1“Essential Story”则自动从 palace 的高权重/最新抽屉生成。集成侧（如 integrations/hermes/init.py）也把 identity.txt 作为 L0 唤醒层读取。

用 --palace 覆盖 palace 路径

所有命令都接受 --palace <path> 覆盖默认位置：

mempalace search "query" --palace /tmp/test-palace
mempalace mine ~/data/ --palace /tmp/test-palace

MCP 服务器同样接受 --palace：

python -m mempalace.mcp_server --palace /custom/palace

该参数在 cli.py 被定义为全局参数，任何子命令都能携带。--palace 的优先级高于环境变量与配置文件（MempalaceConfig.__init__ 将其记为 _palace_path_override，在 palace_path 属性中第一个被检查）。mempalace init --backend <name> 还能把后端选择一并持久化到新 palace（cli.py）。

环境变量速查

文档列出的顶层环境变量如下：

Variable	说明
MEMPALACE_PALACE_PATH	覆盖 palace 路径（等价于 --palace，兼容旧名 MEMPAL_PALACE_PATH）
MEMPAL_DIR	hooks 中自动挖掘（auto-mining）的目录
MEMPALACE_MAX_BACKUPS	覆盖 max_backups 保留数量（0 禁用清理）
MEMPALACE_BACKEND	选择存储后端（默认 chroma），各后端的连接变量见“存储后端”一节
MEMPALACE_MCP_IDLE_HOURS	无 MCP 请求多少小时后服务器自行退出（默认 8；0 禁用），详见 远程服务器指南 的操作说明

结合上文各节的源码分析，还有一批面向具体模块的进阶环境变量（同样遵循“环境变量 > config.json > 默认值”，其中连接类变量几乎都是环境变量优先）：

• MEMPALACE_MILVUS_URI / MEMPALACE_MILVUS_TOKEN / MEMPALACE_MILVUS_DB_NAME / MEMPALACE_MILVUS_NAMESPACE / MEMPALACE_MILVUS_CONSISTENCY_LEVEL
• MEMPALACE_QDRANT_URL / MEMPALACE_QDRANT_API_KEY / MEMPALACE_QDRANT_NAMESPACE / MEMPALACE_QDRANT_TIMEOUT
• MEMPALACE_PGVECTOR_DSN / MEMPALACE_PGVECTOR_NAMESPACE
• MEMPALACE_EMBEDDING_MODEL / MEMPALACE_EMBEDDING_DEVICE / MEMPALACE_EMBEDDING_THREADS，以及 openai-compat 模式下的 MEMPALACE_EMBEDDING_API_URL / MEMPALACE_EMBEDDING_API_MODEL / MEMPALACE_EMBEDDING_API_KEY
• MEMPALACE_ENTITY_LANGUAGES（逗号分隔，实体检测语言）
• MEMPALACE_LANG（本地化主语言）
• MEMPALACE_HOOKS_DAEMON 与 MEMPALACE_HOOKS_AUTO_SAVE（hooks 写路径行为）
• MEMPALACE_TOPIC_TUNNEL_MIN_COUNT（隧道最小共享主题数）

这些变量与 config.json 中对应键的优先级、校验与回退逻辑，均可在 config.py 的 MempalaceConfig 属性实现中找到权威定义。

相关实现与测试入口

想进一步验证上述配置行为，可阅读以下仓库位置：

• 配置核心实现：mempalace/config.py（MempalaceConfig 全量属性、默认常量、原子写入与名称净化）
• 后端注册契约：mempalace/backends/registry.py 与各后端 mempalace/backends/；打包入口点见 pyproject.toml
• CLI 参数与 init 流程：mempalace/cli.py（--palace/--backend 全局参数、init 实体检测与 yaml 写入）
• 项目 YAML 读取与文件路由：mempalace/miner.py、mempalace/room_detector_local.py
• 身份层 L0：mempalace/layers.py
• 配置行为测试：tests/test_config.py、tests/test_config_encoding.py、tests/test_backends.py 等覆盖了解析优先级、写入安全与各后端契约一致性

把这三层（用户全局、项目级、palace 级覆盖）与一套“默认本地、服务端 opt-in”的后端选择配合使用，你就能让同一个 MemPalace 同时服务个人本地记忆、多项目隔离与团队共享记忆三种形态，而无需修改任何业务代码——改的是配置，变的是存储边界。