basicmachines-co/basic-memory

[](https://www.gnu.org/licenses/agpl-3.0) [](https://badge.fury.io/py/basic-memory) [](https://www.python.org/downloads/) [](https://github.com/basicmachines-co/basic-memory/actions) [](https://github.com/astral-sh/ruff)   [](https://deepwiki.com/basicmachines-co/basic-memory) # Basic Memory ### 你的 AI 永不再遗忘。 从你上次停下的地方继续 —— 在 Claude、Codex、Cursor、ChatGPT 或任何支持 [MCP](https://modelcontextprotocol.io) 的工具中。你的知识以 Markdown 文件的形式存在，你和你的 AI 都可以读取、编写和搜索它们。 - **本地优先。** 磁盘上的纯文本。永远如此。 - **双向同步。** AI 和人类写入相同的文件；同步让它们保持步调一致。 - **真正的知识图谱。** 观察记录和 wikilink 相互叠加，构建出丰富的上下文。 - **语义搜索。** 根据含义而不仅仅是关键词来查找笔记。 - **MCP 原生。** 兼容所有主流 AI 客户端和 IDE。 - **渐进式工具发现。** 每个工具都标有行为提示 （只读、破坏性、幂等），因此 agent 可以按需选择正确的工具 — 无需浪费上下文去试错。 - **云服务，可选。** 随时随地在多设备间同步 — 但永远不作强制要求。 ## 快速开始 选择适合你的方式。两种方式都在相同的 Markdown 上运行相同的产品。 **2 分钟。** 安装、配置你的 AI 客户端、运行。 - 永久免费 (AGPL-3.0) - 所有数据都在你的磁盘上 - 支持气隙隔离环境 - 需要通过 [`uv`](https://docs.astral.sh/uv/) 安装 Python ``` uv tool install basic-memory ``` [**配置你的客户端 ↓**](#connect-your-ai-client) ## 云端与本地 | | 云端 | 本地 | |---|---|---| | **设置时间** | 30 秒 | 2 分钟（需要 Python） | | **成本** | $15.00/月，终身锁定（7 天试用） | 免费 | | **存储** | 我们托管 (Tigris S3) | 你的磁盘 | | **跨设备同步** | 内置 | 手动（Git、Syncthing 等） | | **移动端访问** | 支持（网页 + 应用） | 不支持 | | **气隙隔离** | 不支持 | 支持 | | **数据始终归你所有** | 是 — 随时导出 | 是 — 本来就在本地 | | **源代码** | AGPL-3.0 | AGPL-3.0 | | **快照和备份** | 内置 | 自行搭建 | 两种方式都使用相同的开源 (OSS) 引擎和相同的 Markdown 文件。无论哪种方式都没有 锁定 —— 可以在你的需求变化时随时在两者间切换。 ## 兼容你已在使用的工具 | 客户端 | 传输方式 | 说明 | |---|---|---| | 网页应用 | https | 在 basicmemory.com 登录 — 无需安装 | | [Claude Desktop](#claude-desktop) | stdio/https | macOS / Windows / Linux | | [Claude Code](#claude-code) | stdio/https | `claude mcp add` | | [Codex](#codex-cli) | stdio/https | OpenAI 的编程 agent | | [Cursor](#cursor) | stdio/https | `.cursor/mcp.json` | | [VS Code](#vs-code) | stdio/https | 原生 MCP 支持 | | [ChatGPT](#chatgpt) | https | 自定义 GPT 动作 (`search` / `fetch`) | | [Obsidian](#obsidian) | — | 直接读取/写入相同的 Markdown | | 任何支持 MCP 的工具 | stdio/https | 只要它支持 MCP，就能运行 | ## 官方 agent 包 此仓库也是 Basic Memory 宿主原生 agent 包的权威 大本营。核心 Python 包、Claude Code 插件、共享 skills、 Hermes 插件和 OpenClaw 插件均从同一个源代码树发布。 维护者可以从仓库根目录验证整个整合后的代码面： ``` just package-check ``` 当在单个宿主环境中工作时，也可以使用特定于包的 justfiles： ``` just package-check-claude-code just package-check-skills just package-check-hermes just package-check-openclaw ``` ### Claude Code 插件 Claude Code 插件是 Claude 工作记忆与 Basic Memory 之间的桥梁 — 包含会话启动简报、压缩前检查点、可选的捕获 输出样式，以及 `/basic-memory:bm-setup` · `:remember` · `:share` · `:status`。 **请先连接 Basic Memory MCP 服务器** — 参见 [连接你的 AI 客户端](#connect-your-ai-client)。该插件的钩子和 skills 会调用它，因此这是硬性前提。然后添加 marketplace 并安装： ``` claude plugin marketplace add basicmachines-co/basic-memory \ --sparse .claude-plugin plugins/claude-code claude plugin install basic-memory@basicmachines-co ``` 源码：[`plugins/claude-code`](plugins/claude-code)。 ### 共享 skills 与框架无关的 `SKILL.md` 文件位于 [`skills/`](skills) 中。如果你的 Skills CLI 支持仓库子目录源： ``` npx skills add basicmachines-co/basic-memory/skills ``` 如果你安装的 Skills CLI 无法加载该源，请更新 CLI 或将 `skills/` 目录中的 `memory-*` 目录复制到你的 agent 的 skills 目录中。 ### Hermes Hermes 在 [`integrations/hermes`](integrations/hermes) 下保持其原生插件形态： ``` hermes plugins install basicmachines-co/basic-memory --path integrations/hermes ``` 如果你的 Hermes 构建不支持子路径安装，请使用最终废弃的 `basicmachines-co/hermes-basic-memory` 指针发布版本，直到宿主支持 推出。 ### OpenClaw OpenClaw 保持包原生特性，并从 [`integrations/openclaw`](integrations/openclaw) 发布： ``` openclaw plugins install @basicmemory/openclaw-basic-memory ``` ## 从你上次停下的地方继续 https://github.com/user-attachments/assets/a55d8238-8dd0-454a-be4c-8860dbbd0ddc ## 连接你的 AI 客户端 如果你选择了 [云端](#get-started) 方案，网页应用会引导你完成 客户端连接。以下代码片段适用于本地安装。 ### Claude Desktop 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`： ``` { "mcpServers": { "basic-memory": { "command": "uvx", "args": ["basic-memory", "mcp"] } } } ``` 重启 Claude Desktop。默认情况下，笔记保存在 `~/basic-memory` 目录中。

Claude Code、Codex CLI、Cursor、VS Code、ChatGPT、Obsidian

### Claude Code ``` claude mcp add basic-memory -- uvx basic-memory mcp ``` 要获得完整的记忆桥梁 — 会话简报、压缩前检查点 以及 `/basic-memory:*` 命令 — 还需在此基础上安装 [Claude Code 插件](#claude-code-plugin)。 ### Codex CLI 添加至 `~/.codex/config.toml`： ``` [mcp_servers.basic-memory] command = "uvx" args = ["basic-memory", "mcp"] ``` ### Cursor 添加至 `.cursor/mcp.json`（项目）或 `~/.cursor/mcp.json`（全局）： ``` { "mcpServers": { "basic-memory": { "command": "uvx", "args": ["basic-memory", "mcp"] } } } ``` ### VS Code 添加至你的用户设置 (JSON)： ``` { "mcp": { "servers": { "basic-memory": { "command": "uvx", "args": ["basic-memory", "mcp"] } } } } ``` ### ChatGPT Basic Memory 为自定义 GPT 动作提供兼容 OpenAI 的 `search` 和 `fetch` 工具。请参见 [ChatGPT 集成指南](https://docs.basicmemory.com/integrations/chatgpt/?utm_source=github&utm_medium=referral&utm_campaign=readme)。 ### Obsidian 无需设置。将 Obsidian 指向 `~/basic-memory`（或你的项目文件夹）， 你的 AI 写入的相同 wikilink、frontmatter 和 Markdown 就会出现在你的图谱视图中。在任意一端进行编辑 — 同步会处理其余的事情。

尝试输入提示词： ``` "Create a note about our project architecture decisions." "Find information about JWT auth in my notes." "What have I been working on this week?" ``` ## 最新动态 - **自动更新。** Basic Memory 会为 `uv tool` 和 Homebrew 安装方式自动保持最新；`bm update` 会触发手动检查。 - **语义向量搜索。** 根据含义而不仅仅是关键词来查找笔记。 带有 FastEmbed 嵌入的混合全文 + 向量排序，支持 SQLite 或 Postgres。 - **Schema 系统。** 使用 `schema_infer`、`schema_validate`、`schema_diff` 来推断、验证和对比你的 知识库结构。 - **项目级云端路由。** 通过 API 密钥 (`bm project set-cloud`) 将特定项目路由通过云端，同时其他项目保持在本地。 - **更智能的编辑。** 缺失笔记时，`edit_note` 的 append/prepend 会自动创建；`write_note` 可防止意外覆盖。 - **更丰富的搜索结果。** 包含匹配的文本块，以便 LLM 获得 上下文，而不仅仅是命中结果。 - **FastMCP 3.0 + 工具注解。** 每个工具都附带 MCP 行为 提示 (`readOnlyHint`、`destructiveHint`、`idempotentHint`、 `openWorldHint`)，因此 agent 可以在运行时渐进式地发现功能， 而不是猜测或消耗 token。 - **CLI 翻新。** 用于脚本编写的 `--json` 输出、感知工作区的命令， 以及受 htop 启发的项目仪表板。 v0.18 → v0.20 的完整 [CHANGELOG](CHANGELOG.md)。 ## 为什么选择 Basic Memory 大多数 LLM 对话都是短暂的。你提出一个问题，得到答案，然后 一切都被遗忘。替代方案都有其局限性： - **聊天历史** 捕获了对话，但不是结构化的知识。 - **RAG** 让 LLM 可以查询你的文档，但不能回写。 - **向量数据库** 需要复杂的基础设施，通常还托管在别人的云上。 - **知识图谱** 需要专门的工具来维护。 Basic Memory 选择了一条更简单的道路：**人类和 LLM 都可以读写的结构化 Markdown 文件。** - 所有知识都保存在你控制的纯文本文件中。 - 双方都读取和写入相同的文件。 - 带有语义模式的熟悉 Markdown — 无需学习新格式。 - LLM 可以逐个链接跟随遍历的图。 - 兼容你已在使用的编辑器（Obsidian、VS Code 等）。 - 只需文件加上一个本地 SQLite 索引。无需服务器。 ## 工作原理 你正在像平常一样聊咖啡： 让 LLM 记住它： 你的项目目录中实时出现了一个 Markdown 文件： ``` --- title: Coffee Brewing Methods permalink: coffee-brewing-methods tags: [coffee, brewing] --- # 咖啡冲泡方法 ## 观察 - [method] Pour over highlights subtle flavors over body - [technique] Water at 205°F (96°C) extracts optimal compounds - [principle] Freshly ground beans preserve aromatics ## 关系 - relates_to [[Coffee Bean Origins]] - requires [[Proper Grinding Technique]] - affects [[Flavor Extraction]] ``` 在下一次会话中，LLM 会接上话题。它会顺着关系找出 你已知的关于埃塞俄比亚咖啡豆和锥刀磨豆机的信息，并 在此基础上进行构建，而不是从头开始。你在 Obsidian 或 你的编辑器中看到的是相同的文件。手动编辑它们 — AI 也会看到你的更改。 真正的双向流动：人类编辑 Markdown，LLM 通过 MCP 读/写，同步 让一切保持一致，而最终的事实来源永远是你的文件。 ## Markdown 格式 每个文件都是一个 `Entity`。实体包含 `Observations`（关于它们的事实）和 `Relations`（指向其他实体的链接）。这就是全部语法。 ### Frontmatter ``` --- title: type: note permalink: tags: [optional, list] --- ``` ### 观察 关于实体的事实。类别在 `[方括号]` 中，标签用 `#`，可选的 上下文在括号中。 ``` - [method] Pour over highlights subtle flavors - [tip] Grind medium-fine for V60 #brewing - [fact] Lighter roasts contain more caffeine than dark - [resource] James Hoffmann's V60 technique on YouTube - [question] How does temperature affect compound extraction? ``` ### 关系 构成图结构的 Wiki 风格链接。单词 token 的关系类型，或者用 引号引起来的多词类型。 ``` - pairs_well_with [[Chocolate Desserts]] - grown_in [[Ethiopia]] - requires [[Burr Grinder]] - "pairs well with" [[Dark Chocolate]] ``` 纯 `- [[Target]]` 和叙述性文本 `- Worth checking out [[Target]]` 会作为 `links_to` 索引。完整参考请见 [文档](https://docs.basicmemory.com/getting-started/note-formatting/?utm_source=github&utm_medium=referral&utm_campaign=readme)。 ## MCP 工具 Basic Memory 向任何 MCP 客户端公开这些工具。每个工具都标有 MCP 行为提示（只读、破坏性、幂等、开放世界），以便 agent 无需试错即可选择正确的工具： - **内容：** `write_note`、`read_note`、`edit_note`、`move_note`、 `delete_note`、`read_content`、`view_note` - **搜索与发现：** `search`、`search_notes`、`recent_activity`、 `list_directory` - **知识图谱：** `build_context`（导航 `memory://` URL）、 `canvas`（Obsidian 画布生成） - **项目：** `list_memory_projects`、`create_memory_project`、 `get_current_project`、`sync_status- **Schema：** `schema_infer`、`schema_validate`、`schema_diff` - **云端：** `cloud_info`、`release_notes` 所有 MCP 工具默认为文本输出；传入 `output_format="json"` 以获取结构化响应。完整的工具参考见 [文档](https://docs.basicmemory.com/?utm_source=github&utm_medium=referral&utm_campaign=readme)。 ## CLI 要点 ``` # 项目 basic-memory project list basic-memory project add research ~/research basic-memory project set-cloud research # route through cloud basic-memory project set-local research # revert # 健康与维护 basic-memory status basic-memory doctor # file <-> DB consistency check basic-memory tool edit-note ... # CLI access to MCP tools basic-memory update # check for and install updates # Imports basic-memory import claude conversations basic-memory import chatgpt basic-memory import memory-json ``` 路由标志（`--local` / `--cloud`）可在你处于混合模式时强制指定目标。 完整的 CLI 参考请见 [文档](https://docs.basicmemory.com/guides/cli-reference/?utm_source=github&utm_medium=referral&utm_campaign=readme)。 ## 自动更新 CLI 安装默认每 24 小时检查一次更新，并静默应用 （确保 MCP 服务器保持响应）。 - 支持的安装源：`uv tool`、Homebrew - 跳过 `uvx`（由 uv 管理的临时运行时） - 手动：`bm update`（检查 + 应用）或 `bm update --check`（仅检查） 在 `~/.basic-memory/config.json` 中禁用： ``` { "auto_update": false } ``` ## 遥测 少量匿名事件，用于了解 CLI 到云端的转化漏斗。 **我们收集什么：** 云端推广展示次数、云端登录尝试及 结果、推广退出事件。 **我们不收集什么：** 文件内容、笔记标题、知识库数据、PII（个人身份信息）、 IP 地址、按命令或按工具的跟踪。 事件会在后台线程发送到我们的 [Umami Cloud](https://umami.is) 实例 （开源，注重隐私） — 绝不会阻塞 CLI。 选择退出： ``` export BASIC_MEMORY_NO_PROMOS=1 ``` 这将禁用所有推广和遥测。 ## 日志 Basic Memory 使用 [Loguru](https://github.com/Delgan/loguru)。默认值因 入口点而异： | 入口点 | 默认值 | 原因 | |---|---|---| | CLI 命令 | 仅文件 | 不会干扰命令输出 | | MCP 服务器 | 仅文件 | stdout 会破坏 JSON-RPC | | API 服务器 | 文件（本地）或 stdout（云端） | Docker/云端使用 stdout | 日志文件：`~/.basic-memory/basic-memory.log`（10MB 轮换，保留 10 天）。 ### 环境变量 | 变量 | 默认值 | 描述 | |---|---|---| | `BASIC_MEMORY_LOG_LEVEL` | `INFO` | DEBUG / INFO / WARNING / ERROR | | `BASIC_MEMORY_CLOUD_MODE` | `false` | API 日志输出到带有结构化上下文的 stdout | | `BASIC_MEMORY_FORCE_LOCAL` | `false` | 强制本地 API 路由 | | `BASIC_MEMORY_FORCE_CLOUD` | `false` | 强制云端 API 路由 | | `BASIC_MEMORY_EXPLICIT_ROUTING` | `false` | 将路由选择标记为显式 | | `BASIC_MEMORY_ENV` | `dev` | 设置为 `test` 以进入测试模式（仅限 stderr） | | `BASIC_MEMORY_NO_PROMOS` | `false` | 禁用云端推广和遥测 | | `BASIC_MEMORY_IMPORT_UPLOAD_MAX_BYTES` | `104857600` | 导入文件的最大上传大小 | ``` BASIC_MEMORY_LOG_LEVEL=DEBUG basic-memory reindex tail -f ~/.basic-memory/basic-memory.log ``` ## 开发 Basic Memory 支持 SQLite（默认，快速，无需 Docker）和 Postgres （通过 testcontainers — 需要 Docker）。 ``` just install # Install with dev dependencies just test-sqlite # All tests, SQLite just test-postgres # All tests, Postgres (testcontainers) just test # Both backends just fast-check # fix/format/typecheck + impacted tests just doctor # File <-> DB consistency check (temp config) just package-check # Claude Code, skills, Hermes, OpenClaw package checks just lint just typecheck # Pyright (primary) just typecheck-ty # ty (supplemental) just format just check # All quality checks just migration "msg" # New Alembic migration ``` 测试使用 pytest 标记：`windows`、`benchmark`、`smoke`。完整 列表请参见 [justfile](justfile)。 欢迎贡献 — 请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 [AGPL-3.0](LICENSE)。 ## Star 历史 由 [Basic Machines](https://basicmachines.co?utm_source=github&utm_medium=referral&utm_campaign=readme) 用 ♥️ 打造

标签：Markdown, MCP, Python, 人工智能, 无后门, 测试用例, 用户模式Hook绕过, 记忆系统, 语义搜索, 逆向工具, 防御加固