MemPalace 初始化全流程指南环境检查、Palace 建立、MCP 注册与状态验证【免费下载链接】mempalaceThe best-benchmarked open-source AI memory system. And its free.项目地址: https://gitcode.com/GitHub_Trending/me/mempalaceMemPalace 是一款本地优先的开源 AI 记忆系统其初始化流程负责完成「Python 环境校验 → 安装 CLI → 扫描项目目录 → 建立 Palace → 注册 MCP → 状态验证」的完整闭环。本指南以仓库内面向 AI Agent 的初始化指令文档 mempalace/instructions/init.md 为主体结合 mempalace/cli.py 的真实实现逐步骤讲解如何在任意项目目录上完成一次健壮、可复现的 MemPalace 初始化并掌握底层mempalace init的实体探测、房间检测与 Mine 联动机制。阅读完本文你可以独立完成从零到「一个健康的 Palace 可用的 MCP 记忆通道」的全套配置也能在安装或初始化失败时自主定位并修复问题。一、Init 指令的定位Agent 可执行的安装操作手册init.md本身是随包分发的指令文档由mempalace instructions init命令输出给 AI Agent或人工逐条执行。其实现位于 mempalace/instructions_cli.pyCLI 从包内instructions/目录读取同名.md文件并打印到标准输出可用指令集合为init、search、mine、help、status见该文件AVAILABLE常量。运行方式mempalace instructions init # 打印并执行 init 指令执行原则是「按顺序走完每个步骤、出错即停并先修复再继续」这保证了流程可被 Agent 幂等地、容错地完成。整套初始化动作可拆解为八个有序步骤下文逐一展开。二、Step 1–2环境前置检查与「假安装」陷阱2.1 Python 版本校验第一步先验证解释器存在且版本达标python3 --version # Linux / macOS python --version # WindowsMemPalace 要求Python 3.9 及以上。若版本过低或未安装应告知用户补齐 Python 3.9 后停止不要继续。核心运行依赖在安装时自动带入主要包括chromadb0.5.0与pyyaml6.0依据 website/guide/getting-started.md 的 Requirements 说明本地主流程无需任何 API Key。2.2 检测是否已安装警惕「venv 里装了但 PATH 找不到」第二步运行mempalace --version命令成功说明 CLI 已在 PATH 上记录版本号并跳过安装Step 3直接进入 Step 4命令失败不能仅仅因为pip show mempalace或uv tool list显示已安装就跳过 Step 3。这是 init 指令中最容易踩坑的一处包可能安装在一个未激活的虚拟环境里此时命令行command not found后续mempalace init必然失败。因此只要mempalace --version不通过就必须按「未安装」处理继续 Step 3 把 CLI 重新装到 PATH 可见的位置——uv tool install或pip的隔离环境恰好解决了这一痛点。三、Step 3安装 MemPalace——优先 uv含完整降级链路安装阶段优先推荐uv其tool install会把 CLI 装进独立隔离环境并挂到 PATH规避大多数系统 Python 环境问题uv --version # 确认 uv 可用 uv tool install mempalace若uv不在 PATH退回经典方式pip install mempalacePyPI 发布包通过[project.scripts]声明两个可执行入口见 pyproject.tomlmempalace——主 CLI提供init/mine/search/status/instructions等子命令mempalace-mcp——MCP 服务器入口对应mempalace.mcp_proxy:main这也是后续 Step 6 注册 MCP 时命令里mempalace-mcp能直接执行的原因。安装失败的兜底顺序指令文档给出的排障顺序由窄到宽逐条尝试uv tool install失败就换pip install mempalace反之亦然尝试pip3 install mempalace尝试模块方式python -m pip install mempalace或python3 -m pip install mempalace若报错涉及缺失构建工具或编译失败通常来自chromadb及其原生依赖Linux/macOS先补构建链再重试——Debian/Ubuntu 装build-essential与python3-devmacOS 执行xcode-select --installWindows安装 Microsoft C Build Tools 后重试全部失败则清晰上报错误并停止避免无意义重试。四、Step 4–5选择项目目录并初始化 Palace4.1 确定目标目录向用户询问要为哪个项目目录初始化 MemPalace默认提供当前工作目录等待用户确认后再继续。4.2 执行初始化mempalace init --yes dir # dir 为上一步确定的目标目录--yes的含义是自动接受所有探测到的实体非交互场景但它有严格作用域——不隐式触发后续 Mine见下文 Pass 4 行为矩阵。若此步失败应上报错误并停止。4.3 底层到底做了什么init 的五趟扫描从 mempalace/cli.py 的cmd_init实现可以看到init远不止「建个目录」它在一次命令里完成了五个 PassPass 0 — 语料来源判定检测该目录语料是否为 AI 对话写origin.json并提供上下文防止把 Agent 化名误判为人名Pass 1 — 实体发现从 manifest、git 作者、正文描述中探测 people/projects/topics/uncertain 四类实体。--yes在此自动确认全部实体确认结果既写入项目根的entities.json审计文件又合并进全局实体注册表供后续 Mine 读取顶层命名经normalize_wing_name归一保证与room_detector_local写入的 slug 一致Pass 2 — 房间检测调用detect_rooms_local按目录结构生成房间并把mempalace.yaml写入项目写入失败视为硬错误Pass 3 — git 保护把entities.json、mempalace.yaml等按项目生成文件自动追加进.gitignore见_ensure_mempalace_files_gitignored含 issue #185 的 UTF-8 兼容处理Pass 4 — 顺带 Mine 引导_maybe_run_mine_after_init在初始化完成后主动询问是否立即 Mine 刚建立的目录并展示预计文件数与体积估算如~123 files (~4 MB) would be mined消除「忘记敲下一条命令」的摩擦。4.4 何时选择非交互参数组合--auto-mine与--yes的行为矩阵mempalace/cli.py在 CI 或批量初始化场景中非常关键参数组合行为无参数默认交互确认实体 仍询问是否 Mine默认 Yes--yes仅自动接受实体仍会提示Mine 步骤--auto-mine跳过 Mine 询问直接执行 Mine--yes --auto-mine完全非交互的无人值守初始化非交互 stdin 下如管道输入默认视作拒绝 Mine避免阻塞脚本如需自动 Mine 显式传--auto-mine。4.5 定制 Palace 路径与存储后端init尊重--palace/MEMPALACE_PALACE_PATH环境变量issue #1313 修复早期版本会静默忽略该旗标始终落在~/.mempalace。初始化前它会把该环境变量导出使后续所有读取cfg.palace_path的下游Pass 0、cfg.init()、Mine都路由到指定位置。需要自选存储后端时用--backend默认 chroma亦支持 pgvector、qdrant、milvus、sqlite_exact 等见pyproject.toml的 backend 入口声明。五、mempalace init完整参数参考在 mempalace/cli.py 中注册的全部 init 参数如下参数默认值说明dir必填要初始化的项目目录--backendchroma本 Palace 持久化的存储后端--yes关自动接受全部探测实体非交互--auto-mine关跳过 Mine 询问直接开矿配--yes即全自动--lang配置或en实体检测语言如en或en,pt-br同时持久化到 config--no-llm关关闭 LLM 实体精修纯启发式运行无本地 LLM 时避免提示噪音--llm-providerollama可选ollama/openai-compat/anthropic--llm-modelgemma4:e4b所选 provider 的模型名--llm-endpointOllama 默认http://localhost:11434Provider 端点openai-compat 必填--llm-api-key环境变量anthropic 取$ANTHROPIC_API_KEYopenai-compat 取$OPENAI_API_KEY--accept-external-llm关绕过「外部 LLM 上传确认」交互用于 CI需要特别留意的默认值与安全细节源码注释明确标注LLM 精修默认开启旧旗标--llm仅保留向后兼容反义参数是--no-llm外部端点隐私预警当 provider 为 Anthropic、云 openai-compat 等非本地端点时init 会明确提示「目录内容将被发送给 providerMemPalace 无法控制其日志/留存/使用」并在API Key 来自环境变量而非显式--llm-api-key时弹出 y/N 确认门禁issue #24 / #26。拒绝则优雅降级为纯启发式provider 探测优先级为 Ollama localhost 优先、其次 openai-compat、再次 anthropic任何 provider 不可达都不阻塞 init只会打印一行提示并降级到启发式模式。六、Step 6注册 MCP 服务器初始化后需要把 MCP 通道接入 AI 客户端命令按客户端区分# Claude Code claude mcp add mempalace -- mempalace-mcp # Codex CLI codex mcp add mempalace -- mempalace-mcpmempalace-mcp之所以可直接作为命令执行正因为它是由 pyproject.toml 的[project.scripts]安装到 PATH 的独立入口实现见 mempalace/mcp_proxy.py。此步失败不阻塞后续流程上报错误后继续到 Step 7MCP 配置允许稍后手工补做。Cursor 场景则更省事——仓库的 Cursor 插件已自动注册mempalace-mcp无需手工编辑mcp.json见 commands/mempalace-init.md。若还需「保存即自动记忆、会话开始自动召回」的后台能力可再运行仓库内的hooks/cursor/install.sh --scope user安装 Cursor hooks完整讲解见 website/guide/cursor-hooks.md 与 hooks/cursor/README.md。七、Step 7用mempalace status验证 Palace 健康安装是否真正成功最终以状态检查为准mempalace status命令失败或报告错误时应基于输出逐项排查输出正常时确认得到一个健康的 Palace。状态健康度按 mempalace/instructions/status.md 的语义衡量翼wings、房间rooms、抽屉drawers与记忆总数是否就绪。在 MCP 可用时还可追加调用mempalace_status含知识图谱与连通性统计mempalace_kg_stats/mempalace_graph_stats并以「简洁数字摘要」而非长表格展示。八、Step 8初始化完成后的下一步动作初始化完成后告诉用户引导安装流程结束并建议两个后续动作向 Palace 添加数据使用/mempalace:mine——底层即mempalace mine dir可采集代码、文档与笔记project 模式或会话导出--mode convos甚至可选--extract general自动把内容归类为决策、偏好、里程碑、问题与情绪上下文等记忆类型详见 mempalace/instructions/mine.md查询并召回记忆使用/mempalace:search——底层即mempalace search 关键词检索 Palace 中已沉淀的知识。上述两个 skill 分别由 skills/mempalace/SKILL.md 与 skills/mempalace-recall/SKILL.md 承载。更完整的初始化背景与三种模式详解可对照 website/guide/getting-started.md。九、测试背书Init 指令链路的可验证性「指令文档 → CLI 输出」这一机制本身有测试守护。仓库测试文件 tests/test_instructions_cli.py 覆盖了run_instructions对合法指令名逐一成功输出、非法名报错退出、以及.md缺失时的失败路径tests/test_cli.py 中的test_cmd_instructions_calls_run_instructions则验证 CLI 子命令正确转调run_instructions。这意味着 Step 2、Step 5 所依赖的mempalace --version与mempalace init行为在每次发布前都会被自动化回归验证用户可以放心按上文八个步骤执行。十、小结一次成功的初始化等于打通完整记忆链路回顾全文mempalace instructions init所定义的八步流程本质上把三件易错的事固化成了可复现的操作序列环境就绪Python 3.9、CLI 真正在 PATH 上、安装失败有兜底、Palace 就绪实体 房间 git 保护 可选即时 Mine、通道就绪MCP 注册与mempalace status健康验证。在这套流程之后日常使用不再需要手敲命令——AI 会通过 MCP 自动完成mine写入与search召回形成「初始化一次、长期自动记忆」的本地记忆循环。【免费下载链接】mempalaceThe best-benchmarked open-source AI memory system. And its free.项目地址: https://gitcode.com/GitHub_Trending/me/mempalace创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MemPalace 初始化全流程指南：环境检查、Palace 建立、MCP 注册与状态验证
MemPalace 初始化全流程指南环境检查、Palace 建立、MCP 注册与状态验证【免费下载链接】mempalaceThe best-benchmarked open-source AI memory system. And its free.项目地址: https://gitcode.com/GitHub_Trending/me/mempalaceMemPalace 是一款本地优先的开源 AI 记忆系统其初始化流程负责完成「Python 环境校验 → 安装 CLI → 扫描项目目录 → 建立 Palace → 注册 MCP → 状态验证」的完整闭环。本指南以仓库内面向 AI Agent 的初始化指令文档 mempalace/instructions/init.md 为主体结合 mempalace/cli.py 的真实实现逐步骤讲解如何在任意项目目录上完成一次健壮、可复现的 MemPalace 初始化并掌握底层mempalace init的实体探测、房间检测与 Mine 联动机制。阅读完本文你可以独立完成从零到「一个健康的 Palace 可用的 MCP 记忆通道」的全套配置也能在安装或初始化失败时自主定位并修复问题。一、Init 指令的定位Agent 可执行的安装操作手册init.md本身是随包分发的指令文档由mempalace instructions init命令输出给 AI Agent或人工逐条执行。其实现位于 mempalace/instructions_cli.pyCLI 从包内instructions/目录读取同名.md文件并打印到标准输出可用指令集合为init、search、mine、help、status见该文件AVAILABLE常量。运行方式mempalace instructions init # 打印并执行 init 指令执行原则是「按顺序走完每个步骤、出错即停并先修复再继续」这保证了流程可被 Agent 幂等地、容错地完成。整套初始化动作可拆解为八个有序步骤下文逐一展开。二、Step 1–2环境前置检查与「假安装」陷阱2.1 Python 版本校验第一步先验证解释器存在且版本达标python3 --version # Linux / macOS python --version # WindowsMemPalace 要求Python 3.9 及以上。若版本过低或未安装应告知用户补齐 Python 3.9 后停止不要继续。核心运行依赖在安装时自动带入主要包括chromadb0.5.0与pyyaml6.0依据 website/guide/getting-started.md 的 Requirements 说明本地主流程无需任何 API Key。2.2 检测是否已安装警惕「venv 里装了但 PATH 找不到」第二步运行mempalace --version命令成功说明 CLI 已在 PATH 上记录版本号并跳过安装Step 3直接进入 Step 4命令失败不能仅仅因为pip show mempalace或uv tool list显示已安装就跳过 Step 3。这是 init 指令中最容易踩坑的一处包可能安装在一个未激活的虚拟环境里此时命令行command not found后续mempalace init必然失败。因此只要mempalace --version不通过就必须按「未安装」处理继续 Step 3 把 CLI 重新装到 PATH 可见的位置——uv tool install或pip的隔离环境恰好解决了这一痛点。三、Step 3安装 MemPalace——优先 uv含完整降级链路安装阶段优先推荐uv其tool install会把 CLI 装进独立隔离环境并挂到 PATH规避大多数系统 Python 环境问题uv --version # 确认 uv 可用 uv tool install mempalace若uv不在 PATH退回经典方式pip install mempalacePyPI 发布包通过[project.scripts]声明两个可执行入口见 pyproject.tomlmempalace——主 CLI提供init/mine/search/status/instructions等子命令mempalace-mcp——MCP 服务器入口对应mempalace.mcp_proxy:main这也是后续 Step 6 注册 MCP 时命令里mempalace-mcp能直接执行的原因。安装失败的兜底顺序指令文档给出的排障顺序由窄到宽逐条尝试uv tool install失败就换pip install mempalace反之亦然尝试pip3 install mempalace尝试模块方式python -m pip install mempalace或python3 -m pip install mempalace若报错涉及缺失构建工具或编译失败通常来自chromadb及其原生依赖Linux/macOS先补构建链再重试——Debian/Ubuntu 装build-essential与python3-devmacOS 执行xcode-select --installWindows安装 Microsoft C Build Tools 后重试全部失败则清晰上报错误并停止避免无意义重试。四、Step 4–5选择项目目录并初始化 Palace4.1 确定目标目录向用户询问要为哪个项目目录初始化 MemPalace默认提供当前工作目录等待用户确认后再继续。4.2 执行初始化mempalace init --yes dir # dir 为上一步确定的目标目录--yes的含义是自动接受所有探测到的实体非交互场景但它有严格作用域——不隐式触发后续 Mine见下文 Pass 4 行为矩阵。若此步失败应上报错误并停止。4.3 底层到底做了什么init 的五趟扫描从 mempalace/cli.py 的cmd_init实现可以看到init远不止「建个目录」它在一次命令里完成了五个 PassPass 0 — 语料来源判定检测该目录语料是否为 AI 对话写origin.json并提供上下文防止把 Agent 化名误判为人名Pass 1 — 实体发现从 manifest、git 作者、正文描述中探测 people/projects/topics/uncertain 四类实体。--yes在此自动确认全部实体确认结果既写入项目根的entities.json审计文件又合并进全局实体注册表供后续 Mine 读取顶层命名经normalize_wing_name归一保证与room_detector_local写入的 slug 一致Pass 2 — 房间检测调用detect_rooms_local按目录结构生成房间并把mempalace.yaml写入项目写入失败视为硬错误Pass 3 — git 保护把entities.json、mempalace.yaml等按项目生成文件自动追加进.gitignore见_ensure_mempalace_files_gitignored含 issue #185 的 UTF-8 兼容处理Pass 4 — 顺带 Mine 引导_maybe_run_mine_after_init在初始化完成后主动询问是否立即 Mine 刚建立的目录并展示预计文件数与体积估算如~123 files (~4 MB) would be mined消除「忘记敲下一条命令」的摩擦。4.4 何时选择非交互参数组合--auto-mine与--yes的行为矩阵mempalace/cli.py在 CI 或批量初始化场景中非常关键参数组合行为无参数默认交互确认实体 仍询问是否 Mine默认 Yes--yes仅自动接受实体仍会提示Mine 步骤--auto-mine跳过 Mine 询问直接执行 Mine--yes --auto-mine完全非交互的无人值守初始化非交互 stdin 下如管道输入默认视作拒绝 Mine避免阻塞脚本如需自动 Mine 显式传--auto-mine。4.5 定制 Palace 路径与存储后端init尊重--palace/MEMPALACE_PALACE_PATH环境变量issue #1313 修复早期版本会静默忽略该旗标始终落在~/.mempalace。初始化前它会把该环境变量导出使后续所有读取cfg.palace_path的下游Pass 0、cfg.init()、Mine都路由到指定位置。需要自选存储后端时用--backend默认 chroma亦支持 pgvector、qdrant、milvus、sqlite_exact 等见pyproject.toml的 backend 入口声明。五、mempalace init完整参数参考在 mempalace/cli.py 中注册的全部 init 参数如下参数默认值说明dir必填要初始化的项目目录--backendchroma本 Palace 持久化的存储后端--yes关自动接受全部探测实体非交互--auto-mine关跳过 Mine 询问直接开矿配--yes即全自动--lang配置或en实体检测语言如en或en,pt-br同时持久化到 config--no-llm关关闭 LLM 实体精修纯启发式运行无本地 LLM 时避免提示噪音--llm-providerollama可选ollama/openai-compat/anthropic--llm-modelgemma4:e4b所选 provider 的模型名--llm-endpointOllama 默认http://localhost:11434Provider 端点openai-compat 必填--llm-api-key环境变量anthropic 取$ANTHROPIC_API_KEYopenai-compat 取$OPENAI_API_KEY--accept-external-llm关绕过「外部 LLM 上传确认」交互用于 CI需要特别留意的默认值与安全细节源码注释明确标注LLM 精修默认开启旧旗标--llm仅保留向后兼容反义参数是--no-llm外部端点隐私预警当 provider 为 Anthropic、云 openai-compat 等非本地端点时init 会明确提示「目录内容将被发送给 providerMemPalace 无法控制其日志/留存/使用」并在API Key 来自环境变量而非显式--llm-api-key时弹出 y/N 确认门禁issue #24 / #26。拒绝则优雅降级为纯启发式provider 探测优先级为 Ollama localhost 优先、其次 openai-compat、再次 anthropic任何 provider 不可达都不阻塞 init只会打印一行提示并降级到启发式模式。六、Step 6注册 MCP 服务器初始化后需要把 MCP 通道接入 AI 客户端命令按客户端区分# Claude Code claude mcp add mempalace -- mempalace-mcp # Codex CLI codex mcp add mempalace -- mempalace-mcpmempalace-mcp之所以可直接作为命令执行正因为它是由 pyproject.toml 的[project.scripts]安装到 PATH 的独立入口实现见 mempalace/mcp_proxy.py。此步失败不阻塞后续流程上报错误后继续到 Step 7MCP 配置允许稍后手工补做。Cursor 场景则更省事——仓库的 Cursor 插件已自动注册mempalace-mcp无需手工编辑mcp.json见 commands/mempalace-init.md。若还需「保存即自动记忆、会话开始自动召回」的后台能力可再运行仓库内的hooks/cursor/install.sh --scope user安装 Cursor hooks完整讲解见 website/guide/cursor-hooks.md 与 hooks/cursor/README.md。七、Step 7用mempalace status验证 Palace 健康安装是否真正成功最终以状态检查为准mempalace status命令失败或报告错误时应基于输出逐项排查输出正常时确认得到一个健康的 Palace。状态健康度按 mempalace/instructions/status.md 的语义衡量翼wings、房间rooms、抽屉drawers与记忆总数是否就绪。在 MCP 可用时还可追加调用mempalace_status含知识图谱与连通性统计mempalace_kg_stats/mempalace_graph_stats并以「简洁数字摘要」而非长表格展示。八、Step 8初始化完成后的下一步动作初始化完成后告诉用户引导安装流程结束并建议两个后续动作向 Palace 添加数据使用/mempalace:mine——底层即mempalace mine dir可采集代码、文档与笔记project 模式或会话导出--mode convos甚至可选--extract general自动把内容归类为决策、偏好、里程碑、问题与情绪上下文等记忆类型详见 mempalace/instructions/mine.md查询并召回记忆使用/mempalace:search——底层即mempalace search 关键词检索 Palace 中已沉淀的知识。上述两个 skill 分别由 skills/mempalace/SKILL.md 与 skills/mempalace-recall/SKILL.md 承载。更完整的初始化背景与三种模式详解可对照 website/guide/getting-started.md。九、测试背书Init 指令链路的可验证性「指令文档 → CLI 输出」这一机制本身有测试守护。仓库测试文件 tests/test_instructions_cli.py 覆盖了run_instructions对合法指令名逐一成功输出、非法名报错退出、以及.md缺失时的失败路径tests/test_cli.py 中的test_cmd_instructions_calls_run_instructions则验证 CLI 子命令正确转调run_instructions。这意味着 Step 2、Step 5 所依赖的mempalace --version与mempalace init行为在每次发布前都会被自动化回归验证用户可以放心按上文八个步骤执行。十、小结一次成功的初始化等于打通完整记忆链路回顾全文mempalace instructions init所定义的八步流程本质上把三件易错的事固化成了可复现的操作序列环境就绪Python 3.9、CLI 真正在 PATH 上、安装失败有兜底、Palace 就绪实体 房间 git 保护 可选即时 Mine、通道就绪MCP 注册与mempalace status健康验证。在这套流程之后日常使用不再需要手敲命令——AI 会通过 MCP 自动完成mine写入与search召回形成「初始化一次、长期自动记忆」的本地记忆循环。【免费下载链接】mempalaceThe best-benchmarked open-source AI memory system. And its free.项目地址: https://gitcode.com/GitHub_Trending/me/mempalace创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考