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

核心架构组件

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

各组件通过依赖注入容器装配，配置文件由 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 为窗"的经典本地优先架构，三层入口共享同一套服务与模型，确保任意一种访问方式都不会绕过索引一致性逻辑。

概述

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

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。

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）的同步器，负责在三类入口之间协调差异：

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

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 中实现。

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

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

插件与集成层主要注入系统提示、工具描述与权限范围；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）。

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，并在外接编辑器或云同步大量落盘后主动执行重索引以补齐向量嵌入。

Pitfall Log / 踩坑日志

项目：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