Basic Memory

社区

你的AI永不遗忘。

分类: 其他
Stars: ★ 4.1k 非常热门
传输方式: stdio（本地进程）
运行环境: Python 3.12+
凭据: 无需凭据
许可证: AGPL-3.0
最近提交: 今天
工具数: 21

72FMRS · B

Basic Memory 提供了本地优先的双向知识管理能力，与多种 AI 客户端无缝集成。其 Markdown 格式和知识图谱设计使其易于理解和扩展。然而，云服务需付费，且本地模式需要 Python 环境。整体上，它是提升 AI 记忆能力的强大工具，尤其适合重视隐私的开发者。

最强项 · 文档质量 17/20 最弱项 · 可靠性 10/20

可靠性

10/20

安全与权限

15/20

维护活跃度

16/20

文档质量

17/20

安装易用性

14/20

查看各项评分依据

可靠性 10/20: 静态审查，未执行任何代码。README 与 manifest 一致（uvx basic-memory mcp / stdio），工具清单、行为注解、'失败快速失败且不静默回退'等错误处理描述显示设计谨慎，且 MCP 服务器日志仅写文件以避免污染 stdio stdout，这是可靠的信号。但 README 属不可信证据，仓库内 CI 工作流和提交的测试无法从所供源码验证，错误路径仅靠文档声称。按静态校准，无执行证据时可靠性上限为 12，且不确定性应下调，故给 10 分。
安全与权限 15/20: 未触发红线：无恶意代码、无凭据窃取、无隐蔽外传、无不可逆默认操作。本地优先，云模式可选；遥测已明确披露（仅促销展示、登录尝试与结果，不含笔记内容，Umami 托管，BASIC_MEMORY_NO_PROMOS 可完全关闭）；破坏性工具（delete_note 等）带 destructiveHint 注解，Codex 集成保留审批。扣分点：遥测事件仍会离开机器；云路由与可选 reranker 涉及外部网络和 API 密钥（环境变量），但密钥存储与路径作用域（服务器可访问的项目范围）无法从源码验证，确认流程主要依赖客户端侧。故给 15 分。
维护活跃度 16/20: 许可证 AGPL-3.0 明确；manifest 版本 0.22.1，README 变更日志显示 v0.18→v0.20→v0.22 持续发布节奏；自动化更新机制、justfile 质量门禁（lint/typecheck/test/package-check）及多集成（Claude Code 插件、Hermes、OpenClaw）同源维护体现治理成熟。扣分：README 未见显式安全响应渠道（SECURITY.md 或类似披露），issue 响应速度、依赖更新频率无法从静态证据验证。故给 16 分。
文档质量 17/20: README 分层且极完整：云/本地两种安装路径、8 种以上客户端配置示例（含完整 JSON）、工具清单、Markdown 知识格式规范、CLI 参考、环境变量默认值表、日志行为与轮转、遥测与定价披露、限制说明（reranking 默认关闭原因、uvx 跳过自动更新、air-gapped 仅本地）。成本、试用条款清晰。扣分：文档站与完整工具参数表在仓库外无法验证，部分细节依赖外部链接，README 属自述证据。故给 17 分。
安装易用性 14/20: 安装路径清晰且 manifest 与 README 配置示例完全一致（uv tool install 或 uvx basic-memory mcp，stdio），Claude Desktop/Claude Code/Codex/Cursor/VS Code 均给出可直接粘贴的配置块，云路径宣称 30 秒无安装。扣分：本地路径依赖 Python 与 uv 工具链，部分客户端需手动编辑 JSON 文件，且按静态校准无源码内可验证的执行证据，设置分上限为 15；不确定性下调，故给 14 分。

静态评测 · 未实际运行收录于 2026-08-07

查看 FMRS 评分方法 →

选型与风险

能访问什么读取本地文件写入 / 删除本地文件连接数据库

适合谁

注重隐私、希望数据本地保存的个人开发者。
需要 AI 辅助管理大量笔记和知识库的研究人员。
使用 Obsidian 等 Markdown 编辑器的用户。

不适合谁

需要云端同步和移动访问的用户（除非使用付费云服务）。
希望零代码配置的极简用户。
需要大规模向量数据库和复杂检索的场景（仅本地 SQLite 可能不够）。

所需权限

读取和写入本地文件系统（默认在 ~/basic-memory）。
执行文件和目录操作（创建、编辑、删除）。
访问本地 SQLite 数据库（或 Postgres/Milvus，如果配置）。

风险与副作用

工具具有写操作，可能意外修改或删除笔记。
编辑操作可能覆盖现有内容，尽管有保护机制。
语义搜索和重排序功能可能需要下载模型，增加延迟。
本地数据备份由用户自行负责。

安装接入

准备工作

运行环境：Python 3.12+

COHERE_API_KEY 可选密钥使用 LiteLLM 托管重排序（如 cohere/rerank-v3.5）时必需的密钥，从 Cohere 官网获取。

其他可选配置项（12 个）

BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED 可选启用语义向量搜索，设为 true 开启（默认关闭）。

BASIC_MEMORY_RERANKER_ENABLED 可选启用搜索结果重排序（交叉编码器），设为 true 开启。

BASIC_MEMORY_RERANKER_PROVIDER 可选重排序提供方，默认本地 FastEmbed，可设为 litellm 使用托管服务。

BASIC_MEMORY_RERANKER_MODEL 可选重排序模型名称，如 cohere/rerank-v3.5。

BASIC_MEMORY_LOG_LEVEL 可选日志级别，默认 INFO，可设为 DEBUG/INFO/WARNING/ERROR。

BASIC_MEMORY_CLOUD_MODE 可选设为 true 时 API 日志输出到 stdout 并带结构化上下文。

BASIC_MEMORY_FORCE_LOCAL 可选设为 true 强制走本地 API 路由。

BASIC_MEMORY_FORCE_CLOUD 可选设为 true 强制走云端 API 路由。

BASIC_MEMORY_EXPLICIT_ROUTING 可选设为 true 标记路由选择为显式。

BASIC_MEMORY_ENV 可选运行环境，默认 dev，测试时可设为 test（仅输出到 stderr）。

BASIC_MEMORY_NO_PROMOS 可选设为 1 可禁用云服务推广和所有遥测。

BASIC_MEMORY_IMPORT_UPLOAD_MAX_BYTES 可选导入上传大小上限，默认 104857600 字节。

通过 uv 安装 basic-memory，然后在客户端配置 MCP 服务器。例如在 Claude Desktop 中添加：

{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": ["basic-memory", "mcp"]
    }
  }
}

claude_desktop_config.json

{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "basic-memory",
        "mcp"
      ]
    }
  }
}

以 Claude Desktop 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "basic-memory",
        "mcp"
      ]
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add basic-memory -- uvx basic-memory mcp

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

安装后重启客户端，工具列表中应出现 write_note、read_note、search_notes 等 basic-memory 工具；也可以让 AI "写一篇测试笔记再读回来"，成功即说明连接正常。默认笔记存放在 ~/basic-memory。

常见排障

确保已安装 uv 和 Python 3.12+，并检查 MCP 服务器是否成功启动。
可通过 `basic-memory status` 进行诊断，并查看日志文件 `~/.basic-memory/basic-memory.log` 获取错误信息。
如果搜索无结果，检查语义搜索是否启用。

试试这样问

连接成功后，可以直接对 AI 助手这样说：

创建一篇关于我们项目架构决策的笔记。
在我的笔记里搜索关于 JWT 认证的信息。
我这周都在忙什么？
删除那篇过时的部署笔记。

工具能力 21

write_note 写入

创建或覆盖笔记。

read_note 只读

读取笔记内容。

edit_note 写入

编辑笔记，支持追加和前置内容。

move_note 写入

移动笔记到新位置。

delete_note 破坏性

删除笔记。

read_content 只读

读取任意文件内容。

view_note 只读

查看笔记详情。

search_notes 只读

搜索笔记，支持语义和混合搜索。

展开其余 13 个工具

recent_activity 只读

获取最近的活动记录。

list_directory 只读

列出目录内容。

build_context 只读

构建知识图谱上下文，通过 memory:// URLs 导航。

list_memory_projects 只读

列出所有记忆项目。

list_workspaces 只读

列出所有工作区。

create_memory_project 写入

创建新的记忆项目。

delete_project 破坏性

删除记忆项目。

schema_infer 只读

推断知识库的结构模式。

schema_validate 只读

验证知识库的结构模式。

schema_diff 只读

比较知识库的结构差异。

search 只读

兼容 OpenAI 的搜索工具。

fetch 只读

兼容 OpenAI 的获取工具。

basic_memory_diagnostics 只读

运行诊断检查。

使用场景

让 AI 记住你的项目偏好，无需重复解释。

跨会话持续记录和检索知识。

与团队共享一个知识库，供 AI 和人类共同编辑。

支持客户端

Claude Desktop

Claude Code

Codex

Cursor

VS Code

ChatGPT

Obsidian

依据项目文档列出，未经本站实测。

详细介绍

Basic Memory 是一个本地优先的知识管理服务器，通过 Markdown 文件实现人类与 AI 之间的双向同步。它支持知识图谱、语义搜索，并与 Claude、Codex、Cursor 等 MCP 客户端集成，让你和 AI 能共同读写、搜索和管理知识。