MemPalace 本地模型离线接入指南：用 wake-up、CLI 搜索与 AAAK 为 Llama / Mistral 构建零云依赖记忆系统

MemPalace 是面向 AI 的本地优先记忆系统，其核心记忆栈可完全运行在本地。本指南围绕 website/guide/local-models.md 展开，讲解如何在不支持 MCP 的本地 LLM（Llama、Mistral 或任何离线模型）上接入 palace 记忆：通过 mempalace wake-up 把身份与精华故事注入系统提示，用 CLI 或 Python API 按需检索记忆，并用 AAAK 方言进一步压缩上下文，最终组成一套无 API Key、无云依赖的本地记忆工作流。

背景：本地模型为何需要「文本管道」而非 MCP

主流云端 Agent 通过 MCP 协议直接调用 mempalace_search 等工具（见 mempalace/instructions/search.md）。但本地模型——Llama、Mistral 及其他离线模型——通常还不具备 MCP 客户端能力，无法在对话中自主调用工具。因此本地接入退化为两类通用而可靠的途径：

1. Wake-Up Command（上下文体注入）：把 palace 中的「世界观」先拼进模型的 system prompt，让模型一出生就拥有记忆；
2. CLI 搜索 / Python API（按需检索）：在提问前先查询 palace，把命中结果拼进提示词，作为临时的记忆上下文。

这两种方式的共同核心是 MemPalace 的四层记忆栈。在 mempalace/layers.py 的文件头注释中定义了明确的 token 预算设计：

层	内容	规模	加载时机
Layer 0	身份（"我是谁、我在做什么"）	~100 tokens	始终加载
Layer 1	精华故事（palace 中的关键时刻）	~500–800 tokens	始终加载
Layer 2	按需记忆（按 wing / room 过滤）	每次 ~200–500 tokens	主题浮现时
Layer 3	深度语义搜索（ChromaDB）	不限	主动查询时

Wake-up 只需 L0 + L1 合计 ~600–900 tokens，剩余的上下文窗口 95% 以上留给用户对话。这正是本地模型场景能跑通的前提：本地模型上下文窗口往往有限，注入一条有界、精简的「启动上下文」远比塞入整座 palace 可靠。

使用 wake-up 命令把 palace「装入」模型

mempalace wake-up 命令用于生成本地模型的启动上下文，并将结果输出到 stdout，便于重定向到文件：

mempalace wake-up > context.txt
# 把 context.txt 内容粘贴进本地模型的 system prompt

其底层实现位于 mempalace/cli.py 的 cmd_wakeup：它构造 MemoryStack，调用 mempalace/layers.py 的 MemoryStack.wake_up(wing=...)，以 len(text) // 4 估算 token 数并打印。生成内容由两部分拼接而成：

• Layer 0（身份）：读取 ~/.mempalace/identity.txt 纯文本文件。若文件不存在，则输出一段提示文案（见 mempalace/layers.py 的 Layer0）。文件示例格式：

  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.
  

• Layer 1（精华故事）：自动从 ChromaDB 的 mempalace_drawers 集合中抽取高权重 / 最近写入的抽屉并格式化为紧凑摘要（见 Layer1.generate）。常量约束保证了体积上限：最多 15 条时刻（MAX_DRAWERS = 15）、正文硬上限 3200 字符（MAX_CHARS = 3200，约 800 tokens）、最多扫描 2000 条抽屉（MAX_SCAN = 2000），见 mempalace/layers.py。

面向具体项目的启动上下文：--wing

当不同项目应获得不同的「启动记忆」时，可用 --wing 把 L1 限定在某个 wing 内：

mempalace wake-up --wing driftwood > context.txt

传参后 Layer1 会把 where={"wing": self.wing} 作为 ChromaDB 过滤条件，只抽取该项目的关键时刻。CLI 参数定义位于 mempalace/cli.py。

全局可选参数

wake-up 同样接受 CLI 顶层全局参数（mempalace/cli.py）：

• --palace <path>：指定 palace 所在目录，默认读取 ~/.mempalace/config.json 或回退到 ~/.mempalace/palace；
• --backend <name>：本次命令使用的存储后端（默认按 config / 环境变量 / 探测结果选择，通常为 chroma）。

用 CLI 搜索按需取回记忆

如果启动上下文不足以回答当前问题，先运行一次 CLI 搜索，把结果一并喂进提示词：

mempalace search "auth decisions" > results.txt
# 把 results.txt 的内容附加进提示词

cmd_search（mempalace/cli.py）将请求转发到 mempalace/searcher.py 的 search()，返回逐字（verbatim）抽屉内容并支持 wing/room 过滤。CLI 参数（见 mempalace/cli.py）包括：

参数	作用	默认值
query	自然语言搜索语句（位置参数）	必填
--wing <name>	限定某个项目 / wing	全部
--room <name>	限定某个房间（wing 内子类目）	全部
--results <N>	返回结果条数	5
--since <ISO 日期/时间>	只取 filed_at 在此之后（含）的抽屉，如 2026-04-01	无
--before <ISO 日期/时间>	只取 filed_at 严格在此之前的抽屉	无

搜索背后是混合检索：向量索引与（可用时）BM25 词法信号共同参与排序，命中结果附带 similarity 分数与 wing/room/source 元数据，便于你在提示词中为本地模型标注记忆出处。也可通过 mempalace status（mempalace/cli.py）查看 palace 中抽屉总量等状态。

用 Python API 把记忆接进本地推理流水线

对于需要把检索结果写进本地模型 pipeline（脚本 / 本地推理框架 / 批量任务）的场景，应使用编程接口而非 shell 重定向：

from mempalace.searcher import search_memories

results = search_memories(
    "auth decisions",
    palace_path="~/.mempalace/palace",
)

# 把结果格式化为模型的上下文
context = "\n".join(
    f"[{r['wing']}/{r['room']}] {r['text']}"
    for r in results["results"]
)

# 注入本地模型的提示词
prompt = f"Context from memory:\n{context}\n\nUser: What did we decide about auth?"

search_memories 是 MCP 服务器等程序化调用方使用的核心函数，签名在 mempalace/searcher.py，除返回 dict（而非打印）外，还比 CLI search() 暴露更多过滤能力：

• wing / room / source_file：三级出处过滤（source_file 按存储值逐字匹配）；
• since / before：按抽屉 filed_at 的 [since, before) 闭开窗口过滤；
• n_results：返回条数上限，默认 5；
• max_distance：余弦距离阈值过滤。palace 集合使用余弦距离（hnsw:space=cosine），0 表示完全一致、2 表示方向相反；设 0.0 则关闭过滤，实用区间约 0.3–1.0；
• candidate_strategy：混合重排候选池策略，"vector"（默认，取向量索引前 n_results*4 行）或 "union"（额外并入词法命中的 n_results*3 个候选，适合词法信号强但向量距离远的文档）；
• vector_disabled：为 True 时路由到仅 SQLite 的 BM25 兜底路径；
• lang：BM25 停用词过滤的语言代码（未显式设置时读取 MEMPALACE_LANG / MEMPAL_LANG 或 config.json 的 lang）。

搜索按就近相关性返回结构化结果；把 [wing/room] 前缀拼进每一条命中，能让本地模型在引用时知道记忆来自哪条项目/类目，减少张冠李戴。

用 AAAK 方言进一步压缩上下文

长时间运行时，即使每次只有 600–900 tokens 的启动上下文，累计开销依然可观。AAAK 是一种实验性的有损缩写方言，专为压缩高频实体与关系设计。压缩命令支持 dry-run 预览：

mempalace compress --wing myapp --dry-run

cmd_compress（mempalace/cli.py）读取指定 wing（省略则全部）下的抽屉，逐条用 Dialect.compress() 压缩并统计压缩比：

参数	作用
--wing <name>	只压缩某 wing（默认全部 wings）
--dry-run	仅预览、不写入存储
--config <json>	实体配置文件（如 entities.json）；省略时自动探测当前目录或 palace 目录下的同名文件

dry-run 会为每条抽屉打印 [wing/room] source、原始t -> 压缩t (压缩比x) 及压缩文本；非 dry-run 时压缩结果写入 mempalace_closets 集合，并以 compression_ratio、original_tokens 写入元数据。命令总体会输出类似 Total: 12,345t -> 410t (30.1x compression) 的汇总（命令行帮助中对压缩效果的描述为约 30 倍缩减）。

AAAK 的优势与边界都在 website/concepts/aaak-dialect.md 中讲得很清楚：

• 无需解码器：Claude、GPT、Gemini、Llama、Mistral——任何能阅读文本的模型都能直接读懂缩写格式（含实体码如 ALC=Alice、情感码如 vul/joy、结构化 header/zettel/tunnel/arc 行）；
• 不是默认存储格式：MemPalace 默认在 ChromaDB 中保存逐字原文，AAAK 只是可选的压缩层；
• 有损且适合大规模：同一实体重复上百次时省 token 效果明显，但无法还原原文，短文本场景反而因格式开销不划算。

因此对本地模型工作流的建议是：把逐字记忆留给 ChromaDB 深度搜索，把压缩后的 AAAK 文本用于拼进提示词的场景，前提是你接受有损摘要带来的精度折损。

全离线栈与可选的云端边界

原文档明确了核心记忆栈可以离线运行：

• ChromaDB（本机）：向量存储与检索；
• 本地模型（本机）：推理与回答；
• AAAK 压缩（可选）：无云依赖；
• 可选的 reranking 或外部模型集成：取决于你的配置方式，可能引入云端调用——仓库中的重排/嵌入对接示例（如 examples/mx3_public_shim_embeddings_rerank.py）展示了这类外部集成如何被以 shim 方式接入。

判断某一工作流是否「真正离线」，只需看调用链上的四类组件落在哪：检索（ChromaDB 本机）、推理（本地模型）、压缩（AAAK 本机）都离线时，只有显式接入外部 reranker / 云端模型的那条路径会越过本地边界。

组装一条完整的本地记忆工作流

把以上四步串起来，即得到一条可脚本化的本地记忆闭环（以 Bash 为例）：

# 1) 启动上下文：身份 + 精华故事，注入 system prompt
mempalace wake-up --wing driftwood > context.txt

# 2) 提问前按需检索，命中内容并入提示词
mempalace search "auth decisions" --wing driftwood --results 8 > results.txt

# 3) 定期用 AAAK 压缩低频 wing，回收存储并预生成可注入的摘要
mempalace compress --wing legacy --dry-run   # 先预览
mempalace compress --wing legacy             # 确认后真正写入

在代码化场景中，第 2 步换用 search_memories 并自行拼装 [wing/room] text 前缀；模型回答后再用 mempalace mine 把新对话写回 palace（配合 save hook 可在会话结束时自动落库），形成「wake 注入 → 检索增强 → 回答 → 回写」的持续循环。

相关资源导航

• 本指南原始出处：website/guide/local-models.md
• 四层记忆栈实现与 token 预算：mempalace/layers.py
• CLI 路由与命令参数定义：mempalace/cli.py（wake-up/search/compress/status）
• 语义搜索与混合重排实现：mempalace/searcher.py
• AAAK 方言格式、实体码与情感码表：website/concepts/aaak-dialect.md
• CLI 帮助与命令说明：commands/mempalace-search.md、commands/mempalace-status.md

若你的工具链已支持 MCP（如 Claude Code、Cursor、Codex 的云端/宿主侧），则可改用 mempalace/instructions/search.md 中列出的 mempalace_search 等 MCP 工具；对尚不支持 MCP 的本地模型，本文的 wake-up + CLI/Python 检索 + AAAK 压缩即是最实用的接入路径。