# https://github.com/basicmachines-co/basic-memory 项目说明书

生成时间：2026-07-07 02:50:47 UTC

## 目录

- [系统概述与核心架构](#page-1)
- [核心功能与 MCP 工具](#page-2)
- [数据管理与同步引擎](#page-3)
- [扩展、部署与运维](#page-4)

<a id='page-1'></a>

## 系统概述与核心架构

### 相关页面

相关主题：[核心功能与 MCP 工具](#page-2), [数据管理与同步引擎](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/basicmachines-co/basic-memory/blob/main/README.md)
- [docs/ARCHITECTURE.md](https://github.com/basicmachines-co/basic-memory/blob/main/docs/ARCHITECTURE.md)
- [src/basic_memory/__init__.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/__init__.py)
- [src/basic_memory/config.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/config.py)
- [src/basic_memory/api/app.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/api/app.py)
- [src/basic_memory/mcp/server.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/mcp/server.py)
- [src/basic_memory/cli/commands.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/cli/commands.py)
- [src/basic_memory/deps/services.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/deps/services.py)
- [src/basic_memory/file_utils.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/file_utils.py)
- [src/basic_memory/models/entity.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/models/entity.py)
- [src/basic_memory/sync/watch_service.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/sync/watch_service.py)
- [src/basic_memory/cloud/sync.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/cloud/sync.py)
</details>

# 系统概述与核心架构

Basic Memory 是一个本地优先（local-first）的个人知识管理系统，旨在让用户通过纯文本 Markdown 文件（兼容 Obsidian 等编辑器）来组织、链接和检索知识，同时在后台构建一个可语义搜索的关系图谱。系统的核心设计理念是"文件即真相来源"——所有笔记都以普通 `.md`、`.qmd` 等文件形式存储在用户配置的项目目录下，而数据库（SQLite + sqlite-vec）只是为文件建立的派生索引。

## 设计目标与作用域

系统的设计目标是：

- **可移植与可版本控制**：用户笔记以纯文本形式存在，可直接通过 Git、Obsidian 或任何编辑器管理，无需锁定在 Basic Memory 内部。
- **多项目隔离**：每个项目是一个独立的知识工作区，拥有自己的根目录、索引数据库和配置（详见 issue #123 中关于跨项目搜索与实体链接的讨论）。
- **多入口访问**：通过 CLI（`bm` 命令）、REST API（FastAPI）和 MCP 服务器三种方式暴露能力，便于 LLM Agent、脚本与 GUI 客户端调用。
- **可选的云同步**：通过 rclone 进行双向同步（`bm cloud bisync`），但本地始终是主权威。

资料来源：[README.md:1-40]() [src/basic_memory/config.py:1-60]()

## 核心架构组件

系统在进程层面由以下几部分组成，协同构成"读取文件→写入数据库→对外暴露能力"的主链路：

| 组件 | 模块路径 | 职责 |
|---|---|---|
| 配置加载器 | `src/basic_memory/config.py` | 读取 `BASIC_MEMORY_HOME` 与项目配置，发现并创建项目根目录 |
| 文件监视器 | `src/basic_memory/sync/watch_service.py` | 监听项目目录的 on-disk 变更并触发增量索引 |
| 同步服务 | `src/basic_memory/sync/service.py` | 协调文件扫描、frontmatter 解析、实体写入 |
| REST API | `src/basic_memory/api/app.py` | 提供 `/knowledge/entities/{id}` 等 HTTP 端点 |
| MCP 服务器 | `src/basic_memory/mcp/server.py` | 向 LLM Agent 暴露工具方法（read/write/edit/search） |
| CLI | `src/basic_memory/cli/commands.py` | 提供 `bm project`、`bm cloud` 等管理命令 |
| 依赖注入 | `src/basic_memory/deps/services.py` | 统一管理数据库会话、文件服务等生命周期 |

各组件通过依赖注入容器装配，配置文件由 `config.py` 在启动时一次性加载。值得注意的是，配置加载器过去会在用户未配置项目路径时自动创建 `~/basic-memory` 空目录（issue #1029），这是一个被修复的副作用。

资料来源：[src/basic_memory/api/app.py:1-80]() [src/basic_memory/mcp/server.py:1-60]() [src/basic_memory/deps/services.py:1-50]() [src/basic_memory/config.py:60-120]()

## 数据模型与索引流程

系统的核心数据模型围绕"实体（Entity）"展开。一个实体对应项目目录中的一个文件（不限于 Markdown，也支持 `.csv`、`.py`、`.txt`、`.yml` 等，见 issue #1033）。实体模型包含：

- **基础字段**：`id`、`path`、`title`、`note_type`（`note` 或 `file`）、`content_type`、`created_at`、`updated_at`。
- **元数据**：从 YAML frontmatter 解析得到的键值对（解析失败时会被拒绝，见 v0.22.0 release notes）。
- **关系（Relations）**：从 Markdown 中的 `- relation_type [[Target]]` 语法抽取，被存储为可独立查询的图节点（issue #1001 讨论了查询时一跳关系扩展）。
- **向量嵌入**：通过 LiteLLM 抽象层对全文生成 embedding（v0.22.0 引入），存入 sqlite-vec 表以支持语义检索。

索引流程由事件驱动（v0.22.0 引入的 event-index 架构，issue #1002）：当文件监视器检测到写入事件后，同步服务解析 frontmatter、抽取关系、生成 embedding，并原子化地更新实体表与向量表。需要注意的一个已知差异是：直接通过文件监视器写入的文件在被显式 reindex 之前，可能尚未完成向量嵌入（issue #1016）。

资料来源：[src/basic_memory/models/entity.py:1-120]() [src/basic_memory/file_utils.py:1-100]() [src/basic_memory/sync/watch_service.py:1-80]() [src/basic_memory/sync/service.py:1-100]()

## 同步、删除与边界情况

云同步基于 rclone 的 bisync 实现（`bm cloud sync` / `bm cloud bisync`），遵循两个规则：

1. **`.bmignore` 在两端生效**：被忽略的路径既不会上传，也不会被删除，这导致曾经同步过但后来加入 `.bmignore` 的内容在云端成为"孤儿"且无官方清理路径（issue #1032）。
2. **删除是按差异推断的**：扫描时若发现某索引路径在磁盘上不存在，则视为删除。如果扫描因 `PermissionError` 提前返回（被当成"空目录"），就会引发批量误删（issue #1007）。

此外，删除大型云项目（`bm project remove`）在文档中明确不会清理云端租户数据，issue #1034 反映了这一已知的托管租户保留缺口。per-entity 删除端点 `DELETE /knowledge/entities/{id}` 对非 Markdown 实体（`note_type=file`）会返回 500（issue #1033），表明删除路径在文件类型分支上仍有 bug。

资料来源：[src/basic_memory/cloud/sync.py:1-120]() [src/basic_memory/sync/watch_service.py:80-160]() [src/basic_memory/cli/commands.py:1-200]()

整体而言，Basic Memory 采用"文件为主、数据库为辅、API 与 MCP 为窗"的经典本地优先架构，三层入口共享同一套服务与模型，确保任意一种访问方式都不会绕过索引一致性逻辑。

---

<a id='page-2'></a>

## 核心功能与 MCP 工具

### 相关页面

相关主题：[系统概述与核心架构](#page-1), [数据管理与同步引擎](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/basic_memory/mcp/tools/__init__.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/mcp/tools/__init__.py)
- [src/basic_memory/mcp/tools/write_note.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/mcp/tools/write_note.py)
- [src/basic_memory/mcp/tools/read_note.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/mcp/tools/read_note.py)
- [src/basic_memory/mcp/tools/edit_note.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/mcp/tools/edit_note.py)
- [src/basic_memory/mcp/tools/search.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/mcp/tools/search.py)
- [src/basic_memory/mcp/tools/build_context.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/mcp/tools/build_context.py)
- [src/basic_memory/mcp/tools/project.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/mcp/tools/project.py)
- [src/basic_memory/mcp/server.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/mcp/server.py)
</details>

# 核心功能与 MCP 工具

## 概述

Basic Memory 是一个基于本地 Markdown 文件的知识管理系统,通过 MCP（Model Context Protocol）将笔记能力暴露给支持 MCP 的 AI 客户端（如 Claude Desktop、Cursor、Cody 等）。`src/basic_memory/mcp/tools/__init__.py` 中以列表形式集中注册了所有可被 LLM 调用的工具,涵盖笔记读写、搜索、项目管理、对话等多个能力域 资料来源：[src/basic_memory/mcp/tools/__init__.py:1-80]()。

MCP 服务器由 `src/basic_memory/mcp/server.py` 启动,默认通过 stdio 协议与客户端通信,启动时会按需懒加载数据库与文件监听器,确保 LLM 会话内首次工具调用即可使用 资料来源：[src/basic_memory/mcp/server.py:1-60]()。

## 笔记操作工具

笔记操作是 MCP 工具集中最高频的部分,对应底层 `Knowledge` 实体模型,主要包含三类操作:

| 工具 | 用途 | 主要参数 |
|------|------|---------|
| `write_note` | 创建或覆盖整篇笔记 | `title`、`content`、`folder`、`tags` |
| `read_note` | 按标题/路径/ID 读取笔记 | `identifier`、`page`、`page_size` |
| `edit_note` | 在已有笔记上追加或替换段落 | `identifier`、`operation`(append/prepend/find_replace) |

### write_note

`write_note.py` 实现"全量写入"语义,接收 Markdown 文本(含 YAML frontmatter)并解析为 `Entity` 与 `Observation`/`Relation` 列表,持久化到 SQLite 与本地 Markdown 文件 资料来源：[src/basic_memory/mcp/tools/write_note.py:30-90]()。当 `Entity` 已存在时会执行合并而非覆盖,以保留外部编辑器写入的内容。

### read_note

`read_note.py` 支持三种 `identifier` 形态:精确 `permalink`、模糊标题匹配和相对文件路径;返回内容包含元数据、正文以及该实体的关系列表,便于 LLM 在上下文中建立图谱引用 资料来源：[src/basic_memory/mcp/tools/read_note.py:20-70]()。

### edit_note

`edit_note.py` 通过 `find_replace`、`append`、`prepend` 三种 `operation` 实现就地编辑,避免覆盖外部编辑器未同步的更改 资料来源：[src/basic_memory/mcp/tools/edit_note.py:15-75]()。所有改动在事务中提交,并通过事件总线触发增量索引。

## 搜索与上下文构建

### search_notes

`search.py` 实现 `search_notes` 工具,综合全文检索(FTS5)与向量相似度,支持 `query`、`tags`、`entity_types` 等过滤项 资料来源：[src/basic_memory/mcp/tools/search.py:25-95]()。v0.21.5 起 sqlite-vec 在向量表清理前被强制加载,避免因扩展未初始化导致的崩溃 资料来源：[src/basic_memory/mcp/tools/search.py:40-55]()。需要注意的是,搜索目前**不会**跟随关系(`- relation_type [[Entity]]`)做图扩展,这是社区讨论中的活跃需求 资料来源：[issue #1001]()。

### build_context

`build_context.py` 暴露 `build_context` 工具,从 URL/时间窗口/标签组合中拉取记忆片段,并拼接成结构化上下文字符串返回给 LLM 资料来源：[src/basic_memory/mcp/tools/build_context.py:30-110]()。该工具在多轮对话中常被用作"工作记忆",将先前实体、观察、最近项目变更整合到一起。

## 项目管理与云端工具

`project.py` 注册了 `list_projects`、`switch_project`、`create_project`、`delete_project` 等工具,允许 LLM 在多项目工作区之间切换 资料来源：[src/basic_memory/mcp/tools/project.py:1-80]()。v0.21.6 起新增了项目同步元数据查询,团队工作区的 rclone 同步被显式屏蔽以防止误操作 资料来源：[src/basic_memory/mcp/tools/project.py:90-130]()。

云端相关工具(`bm cloud sync`、`bm cloud bisync`)由同一工具集调用,运行时读取项目本地的 `.bmignore` 进行路径过滤。社区已记录两条相关缺陷:`.bmignore` 会同时屏蔽上传与删除,导致已同步内容无法被清除;云端项目删除时缺乏保留期数据清除文档 资料来源：[issue #1032]()、[issue #1034]()。

## 已知问题与限制

- 实体删除接口对 `note_type="file"` 的非 Markdown 文件(`.qmd`、`.csv`、`.py` 等)返回 500,仅 `.md` 能干净删除 资料来源：[issue #1033]()。
- 文件监听器索引外部编辑的文件时**不**生成向量嵌入,需手动重索引才能进入语义搜索结果 资料来源：[issue #1016]()。
- 配置加载器每次都会重建空的 `~/basic-memory` 目录,即使项目路径指向其他位置 资料来源：[issue #1029]()。
- 项目根目录的 `PermissionError` 在扫描阶段被当作"空目录",进而触发批量索引删除 资料来源：[issue #1007]()。
- 跨项目搜索与实体链接目前尚未支持,严格的项目隔离限制了自然的工作流 资料来源：[issue #123]()。

这些约束多数集中在 v0.22.x 修复链上,最新发布的 v0.22.1 已强化发布流程与本地 ASGI 数据库预初始化,部分缓解了 MCP 启动期的崩溃问题 资料来源：[release v0.22.1]()。

---

<a id='page-3'></a>

## 数据管理与同步引擎

### 相关页面

相关主题：[系统概述与核心架构](#page-1), [核心功能与 MCP 工具](#page-2), [扩展、部署与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/basic_memory/db.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/db.py)
- [src/basic_memory/models/knowledge.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/models/knowledge.py)
- [src/basic_memory/models/search.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/models/search.py)
- [src/basic_memory/alembic/versions/3dae7c7b1564_initial_schema.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/alembic/versions/3dae7c7b1564_initial_schema.py)
- [src/basic_memory/sync/sync_service.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/sync/sync_service.py)
- [src/basic_memory/sync/watch_service.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/sync/watch_service.py)
</details>

# 数据管理与同步引擎

`basic-memory` 的数据管理与同步引擎是整套系统的事实来源，负责在本地文件系统、SQLite 数据库、以及远端云租户之间维护实体（entity）、笔记（note）与关系（relation）的一致性。它由项目配置层、SQLAlchemy 数据模型、文件监听服务、以及同步服务四个核心组件构成，共同支撑本地创作、云端协作、以及跨工具（如 Obsidian、外部编辑器）的双向数据流。资料来源：[src/basic_memory/db.py:1-120]()、[src/basic_memory/sync/sync_service.py:1-80]()。

## 项目模型与存储层

引擎的存储入口由 `db.py` 暴露的 `engine`、`SessionLocal` 以及 `Base` 元数据组成，SQLAlchemy 引擎在此被配置为支持 SQLite 与 sqlite-vec 扩展，并初始化 sync、checkpointer 等扩展插件。资料来源：[src/basic_memory/db.py:60-140]()。

数据模型按职责划分为两大类：`Knowledge` 命名空间下的实体（Entity）、Observation、Relation 表，用于保存 markdown 笔记与其衍生结构；`Search` 命名空间下的搜索面记录（SearchIndexRow）则承载用于全文与语义检索的派生视图。资料来源：[src/basic_memory/models/knowledge.py:1-90]()、[src/basic_memory/models/search.py:1-90]()。初始 schema 由 Alembic 迁移 `3dae7c7b1564_initial_schema.py` 创建，主要包括 `entity`、`observation`、`relation`、`search_index` 等表，并预留了向量表。资料来源：[src/basic_memory/alembic/versions/3dae7c7b1564_initial_schema.py:1-200]()。

## 同步服务架构

`sync_service.py` 实现了基于事件索引（event-index）的同步器，负责在三类入口之间协调差异：

| 数据来源 | 说明 |
| --- | --- |
| 文件扫描器 | 读取项目根目录下的 markdown 与支持的非 markdown 文件，按行解析 frontmatter、`[[wikilink]]`、关系声明。 |
| 文件监听器 | 接收 watch_service 推送的本地磁盘变更事件。 |
| 远端租户 | 通过 `bm cloud sync / bisync` 接收的云端事件，与本地事件合并后执行 upsert/delete。 |

同步器采用三阶段流程：1) 收集阶段，从各入口聚合待处理事件；2) 重放阶段，按稳定顺序写入数据库与 markdown 文件；3) 收尾阶段，触发搜索索引刷新。资料来源：[src/basic_memory/sync/sync_service.py:80-260]()。

```mermaid
flowchart LR
    A[文件扫描] --> E[事件索引]
    B[watch_service] --> E
    C[云端 sync/bisync] --> E
    E --> F[SQLite 模型层]
    E --> G[search_index / vec]
    F --> H[知识 API]
    G --> I[search_notes]
```

需要注意的是：当项目根目录抛出 `PermissionError` 时，扫描器会把空目录状态当作“成功扫描”，导致所有已索引的路径被解释为“已删除”，从而触发大规模实体删除。社区已有反馈要求将该异常显式分离。资料来源：[GitHub issue #1007]()。

## 文件监听与外部编辑路径

`watch_service.py` 是直接面向磁盘写入的入口，通常与 Obsidian、`git pull`、云同步落盘等场景绑定。它在事件循环中通过 `watchfiles` 监测 `entity_permalink` 命名的目录结构，命中后调用 `sync_service` 的事件接口。资料来源：[src/basic_memory/sync/watch_service.py:1-120]()。

社区反馈显示：通过该入口写入的文件当前只会进入全文搜索，未触发向量嵌入；用户只有在执行显式 `reindex` 之后，对应的笔记才会出现在语义检索结果中。这一行为被记录在 issue #1016 中。资料来源：[GitHub issue #1016]()。

监听器同样消费 `.bmignore` 规则，社区 issue #1032 指出：被忽略的路径在 `bm cloud sync` 与 `bm cloud bisync` 中既不会上传也不会删除，导致“已同步 → 后被忽略”的内容无法获得受支持的删除通道。资料来源：[GitHub issue #1032]()。

## 已知缺陷与社区关注

围绕数据管理与同步引擎，社区讨论集中于以下几类：

- **云项目清理**：`bm project remove` 在云端大规模删除时缺乏可观测的进度，且没有官方文档说明如何彻底清除已删除云项目遗留的数据（issue #1034）。
- **非 markdown 实体的删除**：`DELETE /knowledge/entities/{id}` 对 `note_type=file` 的实体（`.qmd`、`.csv`、`.py`、`.yml`、同步冲突文件）返回 500；只有 markdown 实体可以正常删除（issue #1033）。
- **配置副作用**：每次配置加载都会重建空的 `~/basic-memory` 目录，即便项目根被显式指向其他位置（issue #1029）。
- **符号链接隔离**：被禁止跟踪的 symlink 目前无法通过“附加知识根”声明来安全放行，限制了组织级共享笔记的复用（issue #871）。
- **关系查询**：搜索阶段尚未对一跳关系做图扩展，导致高语义相关但词项不重叠的笔记无法被召回（issue #1001）。
- **跨项目检索**：项目之间相互隔离，缺少跨项目搜索与跨项目链接的能力（issue #123）。

最新发布 v0.22.1 包含了对 `file_utils` 中 line-anchored frontmatter 校验、就地升级模块预加载等修复，进一步稳定了同步管线。资料来源：[GitHub release v0.22.1]()。用户期待的 Git 自动提交撤销机制（issue #124、#54）也与本引擎紧密相关，但目前尚未在 sync_service 中实现。

---

<a id='page-4'></a>

## 扩展、部署与运维

### 相关页面

相关主题：[核心功能与 MCP 工具](#page-2), [数据管理与同步引擎](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [plugins/claude-code/README.md](https://github.com/basicmachines-co/basic-memory/blob/main/plugins/claude-code/README.md)
- [plugins/codex/README.md](https://github.com/basicmachines-co/basic-memory/blob/main/plugins/codex/README.md)
- [integrations/openclaw/README.md](https://github.com/basicmachines-co/basic-memory/blob/main/integrations/openclaw/README.md)
- [integrations/hermes/README.md](https://github.com/basicmachines-co/basic-memory/blob/main/integrations/hermes/README.md)
- [skills/README.md](https://github.com/basicmachines-co/basic-memory/blob/main/skills/README.md)
- [src/basic_memory/cli/commands/project.py](https://github.com/basicmachines-co/basic-memory/blob/main/src/basic_memory/cli/commands/project.py)
</details>

# 扩展、部署与运维

本页面向运维与集成开发者，介绍 basic-memory 的扩展点（plugins/integrations/skills）、基于 CLI 的本地与云端部署形态，以及日常运维中的同步、监听与回滚注意事项。所有内容基于仓库 `plugins/`、`integrations/`、`skills/` 与 `src/basic_memory/cli/commands/` 下的源码与社区已知问题。

## 扩展体系：插件、集成与 Skills

basic-memory 提供三种扩展层级，分别面向 AI 编码助手、第三方代理与知识工作流：

| 扩展类型 | 路径 | 目标环境 | 启用方式 |
| --- | --- | --- | --- |
| Plugin | `plugins/claude-code/`、`plugins/codex/` | Claude Code / Codex CLI | 通过 plugin manifest 注册到对应 CLI |
| Integration | `integrations/openclaw/`、`integrations/hermes/` | 第三方代理框架 | 复制或软链到代理的扩展目录 |
| Skills | `skills/` | MCP / 客户端侧 | 由客户端在调用 MCP 工具时按需加载 |

插件与集成层主要注入系统提示、工具描述与权限范围；skills 层则提供可复用的提示词与操作流程片段。`plugins/codex/README.md` 中包含与 `plugins/claude-code/README.md` 共享的版本号约定，二者在共享版本升级时需保持一致（参见 v0.22.0 中 `fix(plugins): include codex in shared version bump` 的变更）。

## 部署形态：本地项目与云租户

部署面由 `bm project` CLI 主导，项目元信息维护在 `src/basic_memory/cli/commands/project.py` 中。本地项目以文件系统为唯一真相源，CLI 在初始化时校验配置并自动创建项目根目录；云租户通过 `bm cloud` 子命令族接入。需特别注意以下社区已知问题：

- **`bm project remove` 在本地项目下保留磁盘文件是有意为之**：云端删除大项目时可能出现不透明错误，且当前缺少文档化的"已删除云项目数据清理"路径（issue #1034）。
- **`~/basic-memory` 目录副作用**：每次配置加载时 `mkdir` 副作用会重建一个空目录，即便用户已配置 `BASIC_MEMORY_HOME` 指向其它路径（issue #1029）。
- **`bmignore` 屏蔽同步**：`.bmignore` 同时作用于 `bm cloud sync` 与 `bm cloud bisync` 的两端，已同步内容在加入 `.bmignore` 后无法通过任何受支持的命令删除（issue #1032）。

## 同步、监听与索引一致性

运行时存在三类写入路径：CLI 写、文件监听器写、云同步落盘。运维必须理解它们在索引管道中的差异：

- CLI 通过同步接口写入的笔记会经过完整的事件索引与向量嵌入。
- 直接在磁盘上修改（Obsidian、外部编辑器、`git pull`、云同步落盘）由文件监听器捕获，目前仅建立全文索引，**不**生成向量嵌入，需手动触发重索引才能进入语义搜索（issue #1016、issue #1002 事件索引架构）。
- 项目扫描期间如遇 `PermissionError`，当前会被视为空目录扫描成功，从而触发全量索引删除，造成严重数据丢失（issue #1007）。

社区长期诉求（issue #54、issue #124）希望在 watch service 中集成 Git 自动提交与基于 Git 的撤销/恢复机制，但截至 v0.22.1 仍未合并。

## 安全与多根配置

`file-watcher` 默认拒绝解析到项目根之外的对称链接。运维如需合并组织级共享笔记，应在项目配置中显式声明"额外知识根"以允许安全穿越（issue #871）。在 MCP 服务端，v0.21.5 引入了"工作区限定的写权限永久链接"，跨项目写入需要明确的工作区前缀（`fix(mcp): return workspace-qualified write permalinks`）。运维排障时可结合 `bm cloud login` 的非订阅错误处理改进（v0.21.6）与团队工作区的 `rclone` 同步阻断策略（v0.21.6 中 `fix(cli): block team workspace rclone sync`）。

```mermaid
flowchart LR
  A[CLI 写入] --> M[MCP / CLI API]
  B[文件监听器] --> M
  C[云同步落盘] --> B
  M --> D[(SQLite 索引 + sqlite-vec)]
  B --> D
  D --> E[全文搜索]
  D --> F[语义搜索]
```

部署与运维的最佳实践可归纳为：显式声明所有知识根（含符号链接），定期核对 `.bmignore` 是否屏蔽了需要删除的路径，为项目根设置可读的 ACL 以避免扫描触发 `PermissionError`，并在外接编辑器或云同步大量落盘后主动执行重索引以补齐向量嵌入。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：basicmachines-co/basic-memory

摘要：发现 15 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：Query-time relation traversal in search (one-hop graph expansion)。

## 1. 安装坑 · 来源证据：Query-time relation traversal in search (one-hop graph expansion)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Query-time relation traversal in search (one-hop graph expansion)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/1001 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 配置坑 · 来源证据：[BUG] File-watcher (direct on-disk) writes are not vector-embedded; externally-edited notes silently missing from seman…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[BUG] File-watcher (direct on-disk) writes are not vector-embedded; externally-edited notes silently missing from semantic search until reindex
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/1016 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 安全/权限坑 · 来源证据：[BUG] Large cloud-project deletion errors opaquely; no documented way to purge a removed cloud project's data (hosted-t…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Large cloud-project deletion errors opaquely; no documented way to purge a removed cloud project's data (hosted-tenant retention gap)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/1034 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 4. 安全/权限坑 · 来源证据：[BUG] PermissionError during project scan triggers mass index deletion

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] PermissionError during project scan triggers mass index deletion
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/1007 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 5. 安全/权限坑 · 来源证据：[FEATURE] Please allow additional knowledge roots for safe symlink traversal

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[FEATURE] Please allow additional knowledge roots for safe symlink traversal
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/871 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 6. 安装坑 · 来源证据：[BUG] Empty ~/basic-memory directory recreated on every config load (mkdir side effect in config validator)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] Empty ~/basic-memory directory recreated on every config load (mkdir side effect in config validator)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/1029 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 7. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/basicmachines-co/basic-memory | host_targets=mcp_host, claude, claude_code, cursor, chatgpt

## 8. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/basicmachines-co/basic-memory | README/documentation is current enough for a first validation pass.

## 9. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/basicmachines-co/basic-memory | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/basicmachines-co/basic-memory | no_demo; severity=medium

## 11. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/basicmachines-co/basic-memory | no_demo; severity=medium

## 12. 安全/权限坑 · 来源证据：[BUG] .bmignore shields already-synced content from removal (no supported deletion path)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] .bmignore shields already-synced content from removal (no supported deletion path)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/1032 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 13. 安全/权限坑 · 来源证据：[BUG] `DELETE /knowledge/entities/{id}` returns 500 for non-markdown (file-type) entities

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] `DELETE /knowledge/entities/{id}` returns 500 for non-markdown (file-type) entities
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/1033 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 14. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/basicmachines-co/basic-memory | issue_or_pr_quality=unknown

## 15. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/basicmachines-co/basic-memory | release_recency=unknown

<!-- canonical_name: basicmachines-co/basic-memory; human_manual_source: deepwiki_human_wiki -->