basicmachines-co/basic-memory

AI conversations that actually remember. Never re-explain your project to your AI again. Join our Discord: https://discord.gg/tyvKNccgqN

Basic Memory – 为 LLM 提供持久、可搜索的知识

是什么 – Basic Memory 是一个开源的、以本地为先的知识库，允许大型语言模型（LLM）代理读取和写入人类编辑的相同 Markdown 文件。文件为纯文本，因此您完全拥有数据所有权，但该工具还提供语义搜索索引、基于 wikilink 构建的微型知识图谱，以及一组 MCP 兼容工具，任何 AI 客户端（Claude、Codex、Cursor、VS Code、ChatGPT 等）均可调用。

为何重要 – 大多数 LLM 工作流都是短暂的：对话结束后模型会忘记所有内容。Basic Memory 通过将对话历史转化为结构化、可搜索的笔记，弥合了这一差距，这些笔记可在不同会话、设备甚至云托管同步中持续存在。由于数据以普通 Markdown 格式存储，您可以使用任何编辑器（Obsidian、VS Code、Vim…），且永远不会被锁定在专有格式中。

核心功能（如 README 所述）

纯文本、以本地为先的存储 – 所有笔记均为您磁盘上的普通 Markdown 文件。
双向同步 – 人类编辑文件；LLM 代理可通过 MCP 工具创建、编辑、移动或删除文件。同步层（可选云服务）可保持多设备一致性。
通过 wikilink 构建知识图谱 – [[link]] 语法创建实体和关系，模型可遍历。
语义搜索 – 混合全文 + 向量检索（FastEmbed 嵌入），支持可选的 cross-encoder 重排序以获得更高质量结果。
MCP 原生工具集 – 一组命令（write_note、read_note、search_notes、schema_infer 等），每个命令均带有行为提示（只读、破坏性、幂等、开放世界），使代理能无需试错即可发现功能。
云选项 – 托管版本（Basic Memory Cloud）提供网页、移动端和桌面端访问，自动备份，以及基于 rclone 的冲突解决，月费 $15（7 天免费试用，OSS 折扣码 BMFOSS 可享 3 个月 20% 折扣）。
可扩展集成 – 官方插件支持 Claude Code、Hermes、OpenClaw，以及可添加至任意 MCP 兼容代理的通用“技能”。
模式工具 – schema_infer、schema_validate、schema_diff 可用于推断和强制笔记结构。
CLI 改进 – 支持 JSON 输出、项目感知命令，以及快速状态检查的仪表板。

快速入门（快速路径）

路径	步骤	成本
云服务	1️⃣ 打开网页应用，2️⃣ 连接您的 AI 客户端（Claude、Codex、Cursor 等）	$15/月（7 天免费试用，OSS 折扣码 `BMFOSS` 可享 3 个月 20% 折扣）
本地安装	`uv tool install basic-memory --prerelease=allow`（或 `pip install basic-memory`）→ 配置 AI 客户端的 `mcpServers` 条目 → 运行 `bm` 命令	免费（AGPL-3.0）

README 还展示了如何将服务器添加到特定客户端（Claude 桌面版、Claude Code、Codex CLI、Cursor、VS Code、ChatGPT、Obsidian）。配置完成后，您可以发出如下提示：

创建一篇关于我们项目架构决策的笔记。
在我的笔记中查找有关 JWT 认证的信息。
我本周在做什么？

LLM 将自动创建或检索相应的 Markdown 文件。

典型使用场景

个人知识的 RAG – 存储会议记录、设计决策、代码片段，并让任意 LLM 上下文感知地检索它们。
团队共享上下文 – 通过云工作区，所有团队成员看到相同的笔记；代理可在人类与机器人之间交接任务。
代理驱动的文档生成 – LLM 可在代码变更时自动创建或更新文档（write_note、edit_note）。
AI 增强工作流的快速原型设计 – 将 MCP 工具直接集成到自定义代理（Hermes、OpenClaw 等）中，无需编写新 API 层。
离线环境 – 在安全机器上运行本地版本；数据永远不会离开主机。

安装与运行细节

包管理器 – 推荐使用 uv（uv tool install …）。该包也已在 PyPI 上（pip install basic-memory）。
Python 版本 – 需要 Python 3.12 或更高版本。
可选向量存储 – 对于大型语义索引，可安装 milvus 扩展（basic-memory[milvus]）。
依赖项 – FastMCP 3.0、FastEmbed 用于嵌入，SQLite（默认）或 Postgres 用于向量存储，大部署可选 Milvus。
运行 – basic-memory mcp 启动 MCP 服务器；CLI（bm …）与其通信。just 脚本（just package-check 等）验证所有主机原生代理包是否正确构建。

许可与社区

许可证 – AGPL-3.0（源代码自由可用，修改后必须以相同许可证共享）。
开源徽章 – PyPI 版本徽章、测试工作流徽章、Ruff 代码检查徽章，以及 MCP 服务器/开发徽章，表明 CI 活跃。
社区 – 项目列于 Model Context Protocol (MCP) 排行榜，有 DeepWiki 条目。用户（TrainerDay、Caleb Picker Consulting、@groksrc）的评价已包含在 README 中。

总结

Basic Memory 为 LLM 代理提供了一个实用的、基于文件的记忆层，将普通 Markdown 转化为可搜索、图谱感知的知识库，人类和 AI 均可编辑。可完全本地免费运行，或以适度订阅费用于托管云服务，适用于希望为 AI 工作流获得持久、可控上下文的个人开发者、研究实验室或小团队。