企业官网建设流程全解析

MemPalace 快速上手：init / mine / search 三步搭建本地 AI 记忆系统

【免费下载链接】mempalaceThe best-benchmarked open-source AI memory system. And it's free.项目地址: https://gitcode.com/GitHub_Trending/me/mempalace

从安装到让 AI 替你查询项目记忆，MemPalace 只需要三步命令：init（建宫殿）、mine（采集记忆）、search（检索记忆）。本文以官方快速入门指南为主线，结合仓库源码与指令文档，完整讲解安装方式、初始化行为、两种采集模式与通用抽取策略、检索与 MCP 自动化接入，以及安装失败时的排查路径，让读者读完即可在本地无 API Key 地跑通一套「项目/对话历史 → 可搜索记忆库」的完整工作流。

安装 MemPalace

MemPalace 是一个发布到 PyPI 的 Python 包，CLI 入口在 pyproject.toml 中注册为mempalace = "mempalace.cli:main"，同时提供独立 MCP 服务进程mempalace-mcp = "mempalace.mcp_proxy:main"。

推荐方式：uv

官方推荐使用uv安装，它会将 CLI 隔离到独立环境中并放入 PATH：

uv tool install mempalace

使用uv tool install而不是裸pip的理由，在指令文档 mempalace/instructions/init.md 中有明确说明：它让 CLI 与系统 Python 隔离，能规避绝大多数环境相关问题（例如包被装进某个未激活的 venv，导致mempalace提示command not found）。

备选方式：pip

如果你习惯用 pip，pip install mempalace依然可用；失败时可按顺序尝试pip3 install mempalace、python -m pip install mempalace（或python3 -m pip）。若报错涉及编译或原生依赖（常来自 chromadb），需先安装构建工具：Linux/macOS 装build-essential/python3-dev或运行xcode-select --install，Windows 需安装 Microsoft C++ Build Tools，然后重试。

运行环境要求

依据 pyproject.toml 与入门指南，核心本地工作流有以下硬性门槛：

补充说明：仓库当前版本为 3.8.0，声明依赖中还包含多语言嵌入模型所需的huggingface_hub、tokenizers、numpy等，这些是核心依赖（见 pyproject.toml），但模型本身仍是首次使用时按需下载。可选能力通过 extras 按需启用：mempalace[gpu|dml|coreml]对应不同推理硬件加速（见 pyproject.toml），mempalace[extract]用于 PDF/DOCX/PPTX/XLSX/EPUB/RTF 等办公文档抽取。

特殊平台：Android / Termux

Android 的 Termux 使用 Android 的 Python wheel 平台而非 Linux 的。入门指南明确建议不要在 Termux 里做原生安装，而是改用 Debian PRoot 容器运行 MemPalace，具体步骤见 Termux 指南。

安全提示：识别官方发行渠道

⚠️ 仓库在入门指南中特别警告：域名mempalace.tech是一个品牌抢注（brand-squatting）站点，与本项目无关，已知会运行广告重定向并可能携带恶意软件。MemPalace 的官方发行渠道只有 GitHub 仓库与 PyPI（mempalace包）。切勿从任何非官方域名安装二进制或脚本。

从源码安装

git clone https://github.com/MemPalace/mempalace.git cd mempalace uv sync --extra dev # 或: pip install -e ".[dev]"

源码方式适合希望贡献代码或跟踪最新行为的用户；dev extra 包含 pytest、ruff、mypy、pre-commit 等开发依赖（见 pyproject.toml）。

Quick Start：三步搭建你的记忆宫殿

核心工作流浓缩为三个动作：init → mine → search。命令入口与参数解析集中在 mempalace/cli.py 中（cmd_init在 298 行、cmd_mine在 719 行、cmd_search在 1330 行附近）。

第 1 步：初始化宫殿（init）

mempalace init需要一个待扫描的项目目录作为参数，传路径或.都行：

mempalace init ~/projects/myapp # 或，在项目内部执行： mempalace init .

根据入门指南，该命令会扫描项目目录并完成三件事：

• 从文件内容中识别人物与项目实体（底层调用entity_detector/project_scanner的发现逻辑）
• 依据你的目录结构创建 rooms（房间）（底层为本地房间检测room_detector_local.detect_rooms_local）
• 确保~/.mempalace/配置目录存在（palace 数据默认落盘于此）

仓库指令文档 mempalace/instructions/init.md 给出了更完整的可执行流程，值得照做：

1. 先确认 Python 版本 ≥ 3.9（python3 --version）；
2. 运行mempalace --version检查是否已装好——注意：不要因为pip show mempalace或uv tool list显示已装就跳过重装，包可能位于未激活的 venv 中，后续执行会command not found；
3. 用uv tool install mempalace或pip install mempalace安装到 PATH 可见位置；
4. 询问用户要初始化的项目目录；
5. 执行mempalace init --yes <dir>（--yes跳过交互确认）；
6. 配置 MCP（见下文第 4 步）；
7. 运行mempalace status验证宫殿健康；
8. 展示后续动作（mine / search）。

从源码看，init 并不只是本地启发式扫描：cli.py 中 init默认开启 LLM 辅助实体检测（--llm开、--no-llm是显式退出），provider 优先级为 Ollama localhost → openai-compat → anthropic。当没有可达的 LLM 时，init 不会阻塞，而是打印一行提示并自动回退到纯启发式。需要留意的隐私点是：若选择外部 LLM（如 Anthropic 或云端 openai-compat），你的文件夹内容会在 init 期间发送给该 provider；CLI 会打印外部 API 警告并要求显式同意（--llm-api-key或--accept-external-llm可跳过交互确认，供 CI 使用）。仅本地 Ollama 等端点不会触发该警告，全程保持本地化请加--no-llm。

第 2 步：采集数据（mine）

# 采集项目文件（代码、文档、笔记） mempalace mine ~/projects/myapp # 采集对话导出（Claude、ChatGPT、Slack） mempalace mine ~/chats/ --mode convos # 带自动分类的采集 mempalace mine ~/chats/ --mode convos --extract general

从 CLI 参数定义（cli.py）看，mine提供两类数据来源，外加一种抽取策略：

两种采集模式（--mode）

（此外还有一个依赖mempalace[extract]的--mode extract用于 PDF/DOCX/RTF 等办公文档，详见 CLI 帮助文本。）

一种抽取策略（--extract，仅 convos 模式）

• exchange（默认）——按问答回合抽取；
• general——把内容自动归类为Decisions（决策）/ Preferences（偏好）/ Milestones（里程碑）/ Problems（问题）/ Emotional context（情绪上下文）五类记忆。

mine的常用附加参数（均有 CLI 帮助说明与测试支撑）：

# 指定 wing（默认是目录名） mempalace mine ~/chats/ --mode convos --wing orion # 不尊重 .gitignore mempalace mine ~/projects/myapp --no-gitignore # 强制纳入被忽略路径（可重复或逗号分隔） mempalace mine ~/projects/myapp --include-ignored dist,build # 限制处理文件数（0 = 全部） mempalace mine ~/projects/myapp --limit 100 # 预览而不真正入库 mempalace mine ~/projects/myapp --dry-run # 记录入库 agent 名（默认 mempalace） mempalace mine ~/data/ --agent reviewer

提示：对包含超大会话文件（拼接多个 session 的 mega-files）的目录，先跑mempalace split <dir> [--dry-run]拆分成单会话文件再采，效果更好；--dry-run先预览拆分计划，实际拆分按--min-sessions（默认 2 个会话以上才拆）与--output-dir控制。详细的多项目分 wing、团队共享、agent 标签用法可参见 采深入指南。

第 3 步：搜索（search）

mempalace search "why did we switch to GraphQL"

至此你就拥有了一套可用的本地记忆索引。搜索命令支持 wing / room 过滤与时间窗口，CLI 调用链见 cli.py（转发至searcher.search）：

# 限定 wing mempalace search "database decision" --wing orion # 限定 room mempalace search "database decision" --room backend # 控制返回数量 / 时间范围 mempalace search "xxx" --results 10 --since 2026-01-01 --before 2026-06-01

第 4 步（可选但推荐）：验证与接入 MCP

• 运行mempalace status检查宫殿健康度。指令文档 mempalace/instructions/status.md 要求按 wing / room / drawer / 记忆总量简洁汇总宫殿状态；若接入了 MCP，还可调用mempalace_kg_stats与mempalace_graph_stats获取知识图谱三元组与连通性统计。
• 为 AI 客户端注册 MCP 服务：

# Claude Code claude mcp add mempalace -- mempalace-mcp # Codex CLI codex mcp add mempalace -- mempalace-mcp

注册失败也不必中断，MCP 可稍后手工配置（见 MCP 集成指南 与仓库根目录的 mcp.json）。

安装问题排查速查

综合入门指南与指令文档，按此顺序处理安装问题：

1. uv tool install失败 → 换pip install mempalace（反之亦然）；
2. 再失败 →pip3 install mempalace；
3. 仍失败 →python -m pip install mempalace（Windows 用python，Linux/macOS 用python3）；
4. 若错误提示缺少编译工具 / 原生依赖（chromadb 常见）：
   • Debian/Ubuntu：sudo apt-get install build-essential python3-dev
   • macOS：xcode-select --install
   • Windows：安装 Microsoft C++ Build Tools 后重试；
5. 全部失败 → 如实报告错误并停止，不要猜测。

注意判别一条易踩坑规则：pip show mempalace显示已安装 ≠ CLI 可用，必须mempalace --version成功才算装好；只有 CLI 在 PATH 上，后续的 init/mine 才能找到它（详见 mempalace/instructions/init.md）。

一次性设置之后：交给 AI

MemPalace 的定位是「给 AI 一块长期记忆」，而非日常手动敲命令的工具。一次性完成 init 之后，你的 AI（Claude Code、Codex、Cursor、Gemini 等）会通过 MCP 集成、随附的 Codex 插件或 Claude Code 插件 替你使用它。

届时你只需像聊天一样问：

"What did we decide about auth last month?"

AI 会自动调用mempalace_search工具，拿到逐字（verbatim）结果后组织语言回答你——你从此不必再手动输入mempalace search。

针对带记忆检索能力的 Agent 会话，搜索指令 mempalace/instructions/search.md 给出了更精细的使用约定：优先用 MCP 工具族而非 CLI——mempalace_search(query, wing, room)主检索、mempalace_list_wings/mempalace_list_rooms(wing)探索分类、mempalace_get_taxonomy取全量 wing/room/drawer 树、mempalace_traverse(room)沿知识图谱漫游、mempalace_find_tunnels(wing1, wing2)找跨 wing 隧道。展示结果时必须附带来源归属（wing / room / drawer）与相似度分数，并对多结果按 wing/room 分组。

下一步深入方向

• 深入采集指南——两种采集模式与五类记忆抽取的完整参数详解
• MCP 集成——接入 Claude、Codex、ChatGPT、Cursor、Gemini
• 宫殿概念——理解 wings、rooms、halls、tunnels 的记忆结构设计
• 相关命令文档：init 命令说明、mine 命令说明、search 命令说明

上述所有命令均可在仓库内对应源码与测试中交叉验证：CLI 入口在 mempalace/cli.py，安装元数据与版本约束在 pyproject.toml，init 的完整执行流程见 mempalace/instructions/init.md。

【免费下载链接】mempalaceThe best-benchmarked open-source AI memory system. And it's free.项目地址: https://gitcode.com/GitHub_Trending/me/mempalace