企业官网建设流程全解析

MemPalace Mine 完全指南：将项目、对话与会议记录自动导入本地 AI 记忆库

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

MemPalace 是一个完全本地运行、无需 API Key 的开源 AI 记忆系统。mine（挖掘）是它最重要的数据入口命令：把项目代码、Claude/ChatGPT/Slack 对话导出，甚至普通文档，"咀嚼"成可供检索的逐字记忆抽屉（Drawer）存入 palace。本文以仓库中的 挖掘技能指令 为骨架，结合 CLI 主入口、miner.py、convo_miner.py 等源码，完整讲解从「问清要挖什么」到「确认挖掘结果、衔接后续检索」的六步实战流程，让你和你的 AI Agent 都能把历史语料变成可随时召回的高保真记忆。

1. 理解"挖掘"在 MemPalace 中的位置

在深入命令之前，先建立一张心智地图。MemPalace 把记忆组织成层级结构（见 help.md）：

Wings（项目/人物） +-- Rooms（主题房间） +-- Closets（摘要橱柜） +-- Drawers（逐字记忆抽屉）

• Halls连接同一 wing 内的 rooms；
• Tunnels连接不同 wing 之间的 rooms。

mempalace mine负责把磁盘上的真实语料（源码、文档、对话记录）转化为上述结构中的Drawer（逐字原文）。这里有个关键设计理念：mine 只存储逐字原文，不产生摘要。正如 miner.py 模块注释所述："Stores verbatim chunks as drawers. No summaries. Ever."——绝不丢失信息，这正是"100% 召回"承诺的基础。

存储层面，palace 位于本地，默认用 ChromaDB 做向量检索、SQLite 存元数据，无云服务、无需 API Key；后端还支持 SQLite-exact、PGVector、Qdrant、Milvus 等可插拔实现（见 backends 目录），可通过--backend或配置选择。

mine这个"技能"既是一套给 AI Agent 执行的六步操作流程（记录于 mine.md），也是底层一条真正的 CLI 命令。本文按指令文档的步骤依次展开。

2. 第一步：先问清要挖什么、源数据在哪

技能指令的第一条原则是：不要在信息不全时盲目执行。当用户或 Agent 发起一次挖掘时，首先要澄清三个问题：

1. 来源类型：是项目目录（代码、文档、笔记），还是对话导出（Claude、ChatGPT、Slack），或者是单条对话文件？
2. 期望处理方式：是否需要自动分类（把内容归入 decisions/milestones/problems 等主题）？
3. 去向组织：是否希望归档到某个特定 wing（项目/人物分类）下？

这一步的意义在于决定后续选择哪种"挖掘模式"。CLI 层面对应的正是mine子命令的--mode参数（见 cli.py）：

另外还有一个与--mode互斥的--source <ADAPTER>参数，用于走 RFC 002 定义的第三方 Source Adapter 插件协议。

3. 第二步：选择挖掘模式

3.1 项目挖掘（Project Mining）

mempalace mine <dir>

默认模式，对应源码中的miner.mine()。它扫描目录中的可读文本文件，逐字切块后按内容路由到合适房间。从 miner.py 可以看到，可读扩展名覆盖极广：从.md/.txt/.json/.yaml/.html/.csv/.sql/.toml到.py/.js/.ts/.tsx/.java/.go/.rs/.swift/.kt/.rb/.sh，再到 C/C++（.c/.cpp/.h/.hpp）、C#（.cs/.razor）、PHP 全家族（.php/.twig/.blade等）。

同时它有一组固定跳过名单，例如entities.json、mempalace.yaml、package-lock.json、pnpm-lock.yaml、yarn.lock等元数据文件，避免把锁文件这类噪音挖进记忆库。

3.2 对话挖掘（Conversation Mining）

mempalace mine <dir> --mode convos

把 Claude Code / Claude.ai / ChatGPT / Slack 等对话导出挖掘进 palace。与项目挖掘共用同一个 palace、同一套检索，只是摄取策略不同（convo_miner.py）。

支持的文件扩展名见CONVO_EXTENSIONS（.txt/.md/.json/.jsonl等）。扫描时有几个值得注意的默认行为（convo_miner.py）：

• 跳过符号链接（symlink）与超限大文件，并在 stderr 打印SKIP: <path> (symlink)等提示，保证"为什么这个目录没挖出东西"可见；
• 默认跳过subagents/目录（Claude Code 的子代理会话通常数量庞大），如需挖掘可加--include-subagents；
• .meta.json后缀被排除；
• 直接传入单个对话文件也合法，CLI 会按单文件处理。

对话按问答对（exchange pair）切块：一个>用户轮次 + 其后的 AI 响应作为一个单元。若无>标记则回退为按段落切块；整段 AI 回复保持逐字保留，超长时切分到连续抽屉，绝不静默丢弃（见 chunk 相关的chunk_by_exchange/_chunk_by_paragraph实现）。

对话内容还会按话题关键词自动路由房间（technical/architecture/planning/decisions/problems/general，见 TOPIC_KEYWORDS）。

补充：源码还支持mempalace mine <convo-dir> --mode convos --wing my_app这种把整批对话归档到指定项目 wing 的典型用法，示例见 cli.py 文档字符串。

3.3 自动分类提取（General Extraction）

mempalace mine <dir> --mode convos --extract general

这是对话挖掘的"自动分类"变体：不再是按问答对保存，而是用纯规则启发式把内容抽取为五种记忆类型。--extract有两个取值（见 cli.py）：

底层实现在 general_extractor.py，完全不需要 LLM，靠关键词/模式正则：

1. DECISIONS（决策）—— "we went with X because Y"、"we decided/chose/picked"、"trade-off"、"instead of" 等；
2. PREFERENCES（偏好）—— "always use X"、"never do Y"、"I prefer Z"、"my rule is"；
3. MILESTONES（里程碑）—— "it works"、"figured it out"、"shipped"、"deployed"、"v\d+.\d+"；
4. PROBLEMS（问题）—— "bug/error/crash/broken"、"root cause"、"doesn't work"；
5. EMOTIONAL（情绪）—— 感受、脆弱时刻、人际关系相关表达。

在--extract general模式下，每个记忆片段的memory_type会直接成为目标房间名（见 convo_miner.py），从而自动把对话沉淀为"决策史 / 问题史 / 里程碑史"。

3.4 其他摄取通道（选读）

除了技能指令提到的两种，主命令还支持以下通道，让"mine 同一个 palace、不同摄取策略"的生态更完整：

# 二进制办公文档（PDF/DOCX/PPTX/XLSX/RTF/EPUB，需 mempalace[extract]） mempalace mine <docs-dir> --mode extract # 通过已注册的 Source Adapter 摄取 mempalace mine <source> --source <adapter-name>

extract模式调用 format_miner.py 中的mine_formats()；--source走 sources 目录 的适配器注册表与PalaceContext写入通道，支持--dry-run预演（dry run 时写入走记录型代理，绝不开真实后端，见 cli.py 的 _DryRunCollectionProxy）。

4. 第三步：可选——先切分巨型文件

如果源目录包含超大文件（典型场景是被拼接的多个 Claude Code 会话转录混在一个.txt里），指令建议先切分再挖掘：

mempalace split <dir> [--dry-run]

务必先用--dry-run预览将发生什么，确认无误后再真正执行。实现位于 split_mega_files.py：

• 扫描.txt文件中以"Claude Code v"头部标记的多个会话；
• 区分真实会话起点与会话中途的上下文恢复（后者附近 6 行内会出现 "Ctrl+E ... previous messages" 提示，据此排除，见is_true_session_start）；
• 按会话切分为独立文件，文件名携带日期时间、检测到的人物、首个提问主题；
• 输出到--output-dir（默认与源同目录）；原文件重命名为.mega_backup后缀，不会删除；
• 人物检测基于~/.mempalace/known_names.json的可选名单（names与username_map字段）。

其它命令示例：--min-sessions 2只处理含 2 个以上会话的文件；MEMPALACE_SOURCE_DIR环境变量可改变默认扫描目录。切分后再执行挖掘，可让每个会话的文件级去重、mtime 跟踪与回填日期都精确到单个会话。

5. 第四步：可选——用 --wing 归档到指定项目

若用户希望把挖掘内容归入某个特定 wing（项目/人物），加--wing标志即可：

mempalace mine <dir> --wing <name>

关于 wing 的归属规则，源码给出了清晰的可解释逻辑（convo_miner.py_resolve_wing，项目挖掘由 miner.py 与 config 处理）：

1. 显式--wing永远优先；
2. 未指定时，若源路径是已知 AI 工具目录（如路径含.claude/projects、.codex、.gemini段），自动归入wing_api——把 Claude Code / Codex / Gemini 会话统一收进"API 来源内容"专用 wing；
3. 否则回退到源目录名，经normalize_wing_name规整（小写、空格/连字符折叠为下划线）。

mempalace init、room_detector_local、miner.load_config与convo_miner共享同一套 wing 规整逻辑，保证"init 时探测出的 wing 名 == mine 时的落盘 wing 名"，隧道（tunnel）查找不会因名字不一致而失效。

在 CLI 层，--wing与--agent、--limit、--dry-run等参数并列（见 cli.py）：

6. 第五步：展示进度、汇总结果

选定模式并运行挖掘命令后，应实时展示执行进度；完成后按指令汇总三类信息：

• 挖掘条数（Number of items mined）；
• 应用的分类/归类（Categories or classifications applied），如对话路由到的 topic 房间、general 提取产生的 memory_type；
• 警告与被跳过的文件（Warnings or skipped files），例如 symlink、超限文件、subagents目录等。

6.1 进度展示与重复挖掘保护

挖掘过程中，CLI 会实时输出每个文件的处理情况；SKIP:前缀的提示会说明为什么某文件被略过（符号链接/超大/非普通文件/stat 错误，见 convo_miner.py）。文件级别有去重与重建机制（convo_miner.py）：

• 单文件通过mine_lock串行化，防止并发 Agent 重复归档；
• 已按当前 schema + mtime 归档过的文件直接跳过（file_already_mined），会话转录文件不被假定不可变——Claude Code 会话进行中会不断追加内容，/compact或/clear可能原地重写，因此 mtime 变化会触发"先清旧 drawer 再重建"；
• 批量 upsert 限界分批，崩溃中断的文件会保留完整性记录（chunk_total），下次挖掘能自愈补全；
• 对话内容还做SHA-256 内容哈希去重：同一 wing 下已归档的重复会话不会二次入库（convo_miner.py）。

此外，conversation 的时间戳会尽量回填为真实的会话时间authored_at（取 JSONL 中每条消息 ISO-8601 timestamp 的最大值），保证"几天前的会话即使今天回挖，也按真实日期排列"，不会全部塌缩成入库时间（见_extract_authored_at）。

6.2 结果汇总的底层形态

每个 drawer 写入时会携带结构化元数据（convo_miner.py），这正是"汇总条数与分类"的数据来源：

{ "wing": ..., "room": ..., "hall": ..., "source_file": ..., "chunk_index": ..., "added_by": agent, "filed_at": ..., "entities": [...], "authored_at": ..., "ingest_mode": "convos", "extract_mode": "exchange"/"general", "normalize_version": ..., "id_recipe": ..., "chunk_total": ... }

挖掘完成后，同 wing 下还会自动计算 hallways（走廊）与跨 wing 的 topic tunnels（隧道）等后置逻辑（见 miner.py 引入的compute_hallways_for_wing、palace_graph 的隧道计算），让"同一主题分散在不同 wing"的内容彼此连通。

6.3 与 palace 写入锁的协同

多次挖掘、MCP 写入与后台服务可能同时争夺同一 palace。底层通过非阻塞写入锁协调：已有写入者在运行时，新的mine会以MineAlreadyRunning异常退出并打印持锁者身份（见 cli.py），避免并发堆积；而当本 palace 正在运行mempalace serve的 HTTP hub 时，CLI 会把 mine 任务转发给 hub执行（_forward_mine_to_hub），保证实时会话捕获不被写锁中断。需要强制本地直挖可设MEMPALACE_HUB_FORWARD=0。

7. 第六步：建议下一步

挖掘完成不等于工作结束。指令明确建议引导用户尝试以下后续动作（对应技能命令，详见 help.md）：

search支持按 wing/room 过滤，例如mempalace search "pricing discussion" --wing my_app --room costs（见 cli.py）；状态命令可查看"哪些内容已被归档"。这样，一个完整的「挖掘 → 落盘 → 检索 → 复用」记忆闭环就形成了。

8. 技能指令与命令的联动方式

如果你是在 Claude Code / Cursor 等 Agent 环境中使用，mine还是一条可执行的技能指令。mempalace-mine.md 说明了它的联动方式：插件调用mempalace技能后，运行mempalace instructions mine在终端输出技能指令，再按输出步骤执行。也就是说，本文介绍的 mine.md 六步流程正是由mempalace instructions mine打印给 Agent 的正文——这是"技能文档即运行时指令"的设计。

配套的 Agent 端命令还包括/mempalace:init（初始化）、/mempalace:search（检索）、/mempalace:status（状态）、/mempalace:help（帮助）；对应的 初始化指令、检索指令、状态指令 与 帮助文档 都存放在同目录，可一并阅读。挖掘通常紧跟初始化：mempalace init <dir>在 Pass 4 阶段会主动询问"现在就挖掘这个目录吗？（[Y/n]）"，默认路径是先探测实体与房间、写出mempalace.yaml与entities.json（并自动写入.gitignore，防止误提交），随后立刻进入挖掘。

9. 附：一组从查询到归档的完整命令流

综合上述内容，一个典型的一次性挖掘会话如下：

# 0) 首次使用先初始化（会探测实体、房间并提示是否立即挖掘） mempalace init ~/projects/my_app # 1) 项目挖掘（代码/文档/笔记） mempalace mine ~/projects/my_app # 2) 对话挖掘（Claude Code 导出，归档到指定 wing） mempalace mine ~/.claude/projects/-Users-you-Projects-my_app --mode convos --wing my_app # 2b) 对话自动分类提取（决策/里程碑/问题/偏好/情绪） mempalace mine ~/convo_exports --mode convos --extract general # 3) 巨型拼接转录先切分（先 dry-run 预览） mempalace split ~/Desktop/transcripts --dry-run # 4) 检索刚归档的内容 mempalace search "why did we switch to GraphQL" mempalace status

每条命令都遵循「同一 palace、不同摄取策略、逐字存储、绝不丢信息」的设计哲学：无论来自项目源码、AI 会话还是办公文档，最终都成为可被语义检索、带完整来源元数据的逐字抽屉，让 AI 在未来的任何一次会话中都能精确召回历史事实，而不是依赖摘要或遗忘。

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