Basic Memory：让 AI 拥有持久记忆的开源知识管理工具

从"每次重来"到"记得一切"：一个困扰 AI 开发者的根本问题

想象这样一个场景：你花了一周时间，用 Claude Code 开发了一个复杂的微服务架构，Claude 已经深度理解了你的代码风格、数据库设计决策和 API 约定。第二天你打开新的对话，想要继续优化——却不得不从头解释一切。Claude 不记得你上周关于「订单服务使用事件溯源模式」的讨论，不记得你否决了 Kafka 而选择了 Redis Streams，也不记得那个为了绕过某个框架 bug 而写的权宜之计。

这就是 Basic Memory 试图解决的根本问题：AI 对话缺乏持久上下文。

项目起源：一个"受够了"引发的开源实验

Basic Memory 来自 Basic Machines 公司（hello@basic-machines.co），GitHub 组织 UID 183124417，是一个相对年轻但发展迅速的开源项目。截至分析时，该项目拥有 3100+ Stars、209 次 Fork、83 个正式 Release，以及每月 2500+ 次下载量，Discord 社区活跃。

项目的核心理念非常朴素：与其让 AI 用封闭的向量数据库存储你的"记忆"，不如把知识存成人类和 AI 都能直接读写的 Markdown 文件。这样做有三个关键优势：数据完全由你掌控（没有厂商锁定）、文件格式永恒有效（不会因为某个服务关停而丢失）、你可以随时手动编辑修正 AI 的"记忆"。

技术架构：三层入口 + 依赖注入容器

从架构文档可以看出，Basic Memory 采用了清晰的三层入口模式：

API 层（FastAPI）：提供 REST HTTP 接口，支持 JSON 格式的结构化响应。所有 API 路由遵循统一的 /api/v1/ 路径规范，通过 Pydantic 模型进行请求/响应验证。API 背后是 Service 层（业务逻辑）和 Repository 层（数据访问）的分层设计，职责边界清晰。

MCP 层（FastMCP 1.23.1）：Model Context Protocol 是 Anthropic 主导的 AI 工具互操作协议，Basic Memory 通过它将自己暴露为 AI 客户端可调用的工具集。核心工具包括：write_note、read_note、edit_note、search、schema_infer、schema_validate 等。工具还支持 output_format="json" 返回结构化数据。MCP 架构采用了客户端委托模式（Client Delegation），每个功能域（knowledge、search、memory、directory、resource、project）都有独立的 *Client 类，继承自 BaseClient，封装了 HTTP 路径和响应验证逻辑。

CLI 层（Typer）：提供命令行界面，入口命令为 basic-memory 和 bm，支持本地文件管理和同步操作。

容器模式（Composition Root）：三个入口各自有独立的 Container 类（ApiContainer、McpContainer、CliContainer），通过 runtime.py 中的 RuntimeMode 枚举（LOCAL / CLOUD / TEST）决定全局行为。依赖注入遵循"只有组合根读取全局配置，其他模块显式接收配置"的原则，避免了隐藏的全局状态耦合。

存储层：双引擎支持（SQLite + PostgreSQL）

数据持久化支持两种后端：**SQLite（默认）**和 PostgreSQL（生产推荐）。通过 Alembic 实现数据库迁移（alembic/ 目录），同时支持 Postgres 的 async 驱动 asyncpg。默认数据目录为 ~/.basic-memory/，日志使用 Loguru（10MB 轮转，保留10天）。

核心数据库表围绕 Entity（实体） 设计——每个 Markdown 文件对应一个 Entity，数据库中存储的是文件的元数据和解析后的结构化数据（wikilinks、frontmatter、observations）。这种"文件即实体"的思路与 Obsidian 的 Vault 模式高度兼容，也是项目支持与 Obsidian 直接互操作的基础。

搜索能力：向量嵌入 + sqlite-vec

项目使用 FastEmbed 进行向量嵌入，配合 sqlite-vec 实现本地向量搜索。这意味着在本地模式下也能获得语义搜索能力，而不需要连接云端 API 或自建 Elasticsearch。对于需要更强大搜索的场景（如 Cloud 版本），还可以路由到云端搜索服务。

MCP 工具生态：不仅仅是笔记

除了基础的笔记 CRUD，Basic Memory 的 MCP 工具覆盖了更广泛的上下文管理场景：

• session 管理：recent_activity 查看最近活动，build_context 构建会话上下文
• 项目路由：支持多项目管理，通过 ProjectMode（LOCAL / CLOUD）区分路由策略，解决"选择正确的客户端来验证项目存在"的引导悖论
• 知识图谱：schema_infer 从笔记内容推断实体关系，schema_validate 验证笔记格式合规性
• 同步：支持与云端的双向同步，通过 rclone 处理冲突解决

部署体验：本地安装 vs 云端托管

本地安装极其轻量——一行命令 uv tool install basic-memory 即可完成安装，依赖 Python 3.12+。不需要 GPU，不需要大内存，100MB 磁盘空间足够。项目提供了完整的 Dockerfile（基于 python:3.12-slim-bookworm，多阶段构建，最终用 uv 安装 Python 3.13）和 docker-compose.yml（支持一键启动带 PostgreSQL 的完整环境）。

云端托管（basicmemory.com）提供跨设备同步、移动端访问和快照备份，月费 $15（beta 价格锁定终身）。对于开源用户，使用优惠码 BMFOSS 可再享 20% 折扣。值得注意的是，云端和本地使用完全相同的引擎和 Markdown 文件格式，两者可以随时切换，不存在数据迁移的锁定问题。

代码质量：测试覆盖完善，代码规范严格

从 pyproject.toml 可以看出项目使用 pytest + pytest-asyncio 进行测试，支持代码覆盖率报告（--cov=basic_memory --cov-report term-missing），测试目录包含 tests/（单元测试）和 test-int/（集成测试），测试标记包括 benchmark（性能基准）、slow（慢速测试）、postgres（需要 Postgres 后端的测试）和 smoke（快速冒烟测试）。代码规范使用 Ruff（Astral 家的 linter），CI 包含 GitHub Actions 自动化测试流程。

隐私与安全

项目明确承诺不收集笔记内容、笔记标题、个人身份信息或 IP 地址，只收集最小化的匿名遥测数据（云端推广展示次数、登录尝试）。所有数据存储在用户本地或用户授权的云端账户下，隐私优先。

局限与挑战

首先，Basic Memory 不是一个独立的 Web 应用——它是一个后端服务，需要配合 Claude Desktop、Claude Code、Codex、Cursor 等 AI 客户端使用。对于只想在浏览器中管理笔记的用户，云端托管是唯一选择。其次，MCP 协议本身仍在快速发展（FastMCP 当前版本 3.3.1），项目需要持续跟进协议变更。第三，多项目管理（per-project routing）的实现相对复杂，对于简单使用场景可能显得过于重量。

行业意义：重新定义 AI 的"记忆"范式

Basic Memory 代表了一种新兴的 AI 记忆架构趋势：本地优先、文件驱动、MCP 集成。与传统的 RAG（检索增强生成）系统相比，它放弃了向量数据库的封闭性，选择了 Markdown 这种最通用的知识表示格式。与闭源的 AI 记忆产品（如 Mem.ai、Notion AI）相比，它的所有代码都公开，用户对数据有完全的控制权。

GitHub 3100+ Stars 的增长曲线说明，这个方向确实击中了开发者的真实痛点。随着 MCP 协议被更多 AI 工具采用（如 Cursor、VS Code Copilot），Basic Memory 的适用范围有望进一步扩大。