🚀 Basic Memory 云端版现已上线！

跨设备多平台支持：您的知识图谱现在可在桌面端、网页端和移动端无缝同步，兼容所有AI工具（Claude、ChatGPT、Gemini、Claude Code和Codex）
早鸟优惠：早期用户永久享受25%折扣开源项目持续更新，云端版让知识随处可用

立即注册 →

享受7天免费试用

Basic Memory

Basic Memory 让您通过与Claude等大语言模型（LLMs）的自然对话构建持久化知识，同时将所有内容以简单Markdown文件形式保存在本地。它采用模型上下文协议（MCP），使任何兼容LLM都能读写您的本地知识库。

官网：https://basicmemory.com
文档：https://docs.basicmemory.com

随时接续上次对话

AI助手可从本地文件加载上下文开启新对话
笔记实时以Markdown格式保存到本地
无需项目知识或特殊提示词

https://github.com/user-attachments/assets/a55d8238-8dd0-454a-be4c-8860dbbd0ddc

快速开始

# 推荐使用uv安装
uv tool install basic-memory

# 配置Claude桌面版（编辑~/Library/Application Support/Claude/claude_desktop_config.json）
# 添加如下配置：
{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "basic-memory",
        "mcp"
      ]
    }
  }
}
# 现在在Claude桌面版中您可以：
# - 通过"创建关于咖啡冲泡方法的笔记"写笔记
# - 通过"我对滴滤咖啡了解多少？"读笔记
# - 通过"查找埃塞俄比亚咖啡豆信息"进行搜索

默认存储位置为~/basic-memory目录，您可随时查看共享上下文。

为什么选择Basic Memory？

多数LLM交互都是临时的——提问、获得答案后一切就被遗忘。每段对话都从零开始，无法继承先前上下文。现有解决方案存在局限：

聊天记录仅保存对话而非结构化知识
RAG系统可查询文档但不允许LLM回写
向量数据库配置复杂且多部署在云端
知识图谱通常需要专业工具维护

Basic Memory通过简单方案解决这些问题：使用人类和LLM都能读写的结构化Markdown文件。核心优势：

本地优先：所有知识存储于您掌控的文件中
双向交互：人类与LLM共同读写相同文件
简洁结构化：采用熟悉的Markdown语义化格式
可遍历知识图谱：LLM可跟随主题链接跳转
标准格式：兼容Obsidian等常用编辑器
轻量架构：仅需本地文件和SQLite数据库

使用Basic Memory，您可以：

开展延续性对话
在自然对话中创建结构化笔记
与"记忆"先前讨论内容的LLM交流
语义化导航知识图谱
完全本地化掌控数据
使用Obsidian等工具查看编辑笔记
构建持续增长的个人知识库
通过双向同步实现云端备份
通过订阅验证管理云端项目
直接挂载访问云存储文件

实际应用示例

假设您正在研究咖啡冲泡方法：

开始常规对话：

我最近尝试了不同咖啡冲泡方法，主要发现：
- 滴滤法比法压壶更能凸显风味层次
- 水温至关重要——约205°F效果最佳
- 现磨咖啡豆带来显著差异

...继续对话

让LLM帮助结构化知识：

"我们来写份关于咖啡冲泡方法的笔记"

LLM将在本地创建Markdown文件（可通过Obsidian实时查看）：

---
title: 咖啡冲泡方法
permalink: coffee-brewing-methods
tags:
- 咖啡
- 冲泡
---

# 咖啡冲泡方法

## 观察记录

- [方法] 滴滤法能更好呈现细腻风味
- [技巧] 96°C水温可最佳萃取化合物
- [原则] 现磨咖啡豆保留最佳香气

## 关联关系

- 关联到 [[咖啡豆产地]]
- 需要 [[研磨技巧]]
- 影响 [[风味萃取]]

文件默认保存在~/basic-memory目录

运行basic-memory sync --watch启用实时同步

在对话中引用主题：

查看`coffee-brewing-methods`获取滴滤咖啡背景

LLM将构建丰富上下文：

根据'关联到[[咖啡豆产地]]'关系：
- 找到埃塞俄比亚耶加雪菲信息
- 哥伦比亚豆的坚果风味笔记
- 海拔对豆特性的影响

根据'需要[[研磨技巧]]'关系：
- 磨盘式与刀片式磨豆机对比
- 不同冲泡法的研磨度建议
- 颗粒均匀度对萃取的影响

技术实现

底层机制：

所有内容存储为Markdown文件
使用SQLite数据库实现搜索索引
通过简单Markdown模式提取语义：
- 文件转为实体对象
- 每个实体包含观察项（事实记录）
- 关系连接实体构建知识图谱
维护基于文件的本地知识图谱
提供文件与图谱的双向同步
实现MCP协议支持AI集成
提供图谱遍历工具集
使用memory://URL实现跨工具引用

文件格式说明：

前置元数据

title: <标题>
type: <类型>
permalink: <固定链接>
- <标签等元数据>

观察项

采用特殊格式的Markdown列表项，可包含类别、标签（#前缀）和上下文：

- [类别] 内容 #标签 (上下文)

示例：

- [方法] 滴滤法突出花香调
- [技巧] 滴滤适用中细研磨 #冲泡
- [发现] 浅烘豆通常咖啡因含量更高

关系

定义知识图谱连接：

- 关系类型 [[链接]] (上下文)

示例：

- 搭配 [[巧克力甜点]]
- 需要 [[磨盘式磨豆机]]
- 区别于 [[茶道]]

VS Code集成

在用户设置(JSON)中添加：

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

或创建.vscode/mcp.json实现团队共享配置。

通过VS Code扩展，您可以在编程时便捷存取知识库信息。

与Claude桌面端配合使用

Basic Memory基于MCP（模型上下文协议）构建，可与Claude桌面应用（https://claude.ai/）协同工作：

配置Claude桌面端使用Basic Memory：

编辑MCP配置文件（macOS系统通常位于~/Library/Application Support/Claude/claude_desktop_config.json）：

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

如需使用特定项目（参见下方多项目管理），更新Claude桌面端配置：

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

同步知识库：

# 一次性同步本地知识更新
basic-memory sync

# 启动实时同步进程（推荐）
basic-memory sync --watch

云功能（可选，需订阅）：

# 云端认证
basic-memory cloud login

# 双向云端同步
basic-memory cloud sync

# 验证云端完整性
basic-memory cloud check

# 挂载云存储
basic-memory cloud mount

路由标识（面向云订阅用户）：

启用云模式时，CLI命令默认与云端API通信。使用路由标识可覆盖该行为：

# 强制本地路由（适用于云模式启用时访问本地MCP服务器）
basic-memory status --local
basic-memory project list --local

# 强制云端路由（云模式禁用时访问云端）
basic-memory status --cloud
basic-memory project info my-project --cloud

本地MCP服务器（basic-memory mcp）自动采用本地路由，因此可同时使用本地Claude桌面端和云端客户端。

在Claude桌面端中，LLM现可使用以下工具：

内容管理：

write_note(标题, 内容, 文件夹, 标签) - 创建/更新笔记
read_note(标识符, 页码, 页大小) - 通过标题或永久链接读取笔记
read_content(路径) - 读取原始文件内容（文本/图像/二进制）
view_note(标识符) - 以格式化文档查看笔记
edit_note(标识符, 操作, 内容) - 增量编辑笔记
move_note(标识符, 目标路径) - 保持数据库一致性的笔记移动
delete_note(标识符) - 从知识库删除笔记

知识图谱导航：

build_context(网址, 深度, 时间范围) - 通过memory://协议导航知识图谱
recent_activity(类型, 深度, 时间范围) - 查找近期更新信息
list_directory(目录名, 深度) - 带筛选条件的目录浏览

搜索发现：

search(查询, 页码, 页大小) - 全知识库搜索
search_notes(查询, 页码, 页大小, 搜索类型, 类型, 实体类型, 截止日期, 元数据筛选, 标签, 状态, 项目) - 带筛选器的笔记搜索
search_by_metadata(筛选器, 限制, 偏移量, 项目) - 结构化Frontmatter搜索

项目管理：

list_memory_projects() - 列出所有可用项目
create_memory_project(项目名, 项目路径) - 创建新项目
get_current_project() - 显示当前项目统计
sync_status() - 检查同步状态

可视化：

canvas(节点, 边, 标题, 文件夹) - 生成知识可视化

示例提示词：

"创建关于项目架构决策的笔记"
"在我的笔记中查找JWT认证相关信息"
"为我的项目组件创建可视化画布"
"阅读我关于认证系统的笔记"
"我过去一周处理过哪些工作？"

扩展信息

详见官方文档获取：

完整用户指南
CLI工具
云CLI与同步
多项目管理
从OpenAI/Claude项目导入数据

日志系统

Basic Memory采用Loguru记录日志，不同入口点行为各异：

入口点	默认行为	适用场景
CLI命令	仅文件记录	避免日志干扰命令输出
MCP服务器	仅文件记录	标准输出会破坏JSON-RPC协议
API服务器	文件(本地)/标准输出(云端)	Docker/云端部署使用标准输出

日志文件位置： ~/.basic-memory/basic-memory.log（10MB轮转，保留10天）

环境变量

变量名	默认值	描述
`BASIC_MEMORY_LOG_LEVEL`	`INFO`	日志级别：DEBUG/INFO/WARNING/ERROR
`BASIC_MEMORY_CLOUD_MODE`	`false`	为`true`时API输出结构化上下文日志
`BASIC_MEMORY_FORCE_LOCAL`	`false`	为`true`时强制本地API路由（忽略云模式）
`BASIC_MEMORY_ENV`	`dev`	测试模式设为`test`（仅标准错误输出）

示例

# 启用调试日志
BASIC_MEMORY_LOG_LEVEL=DEBUG basic-memory sync

# 查看日志
tail -f ~/.basic-memory/basic-memory.log

# 云/Docker模式（标准输出结构化上下文日志）
BASIC_MEMORY_CLOUD_MODE=true uvicorn basic_memory.api.app:app

开发指南

运行测试

支持双数据库后端（SQLite和Postgres）。默认使用SQLite测试，设置BASIC_MEMORY_TEST_POSTGRES=1可测试Postgres（需Docker运行testcontainers）。

快速开始：

# SQLite测试（默认，快速）
just test-sqlite

# Postgres测试（使用testcontainers）
just test-postgres

# 双数据库测试
just test

可用测试命令：

just test - 双数据库全测试
just test-sqlite - SQLite全测试（无需Docker）
just test-postgres - Postgres全测试（需testcontainers）
just test-unit-sqlite - SQLite单元测试
just test-unit-postgres - Postgres单元测试
just test-int-sqlite - SQLite集成测试
just test-int-postgres - Postgres集成测试
just test-windows - Windows专属测试（其他平台自动跳过）
just test-benchmark - 性能基准测试
just testmon - 变更影响测试（pytest-testmon）
just test-smoke - MCP端到端冒烟测试
just fast-check - 快速检查（修复/格式化/类型检查+影响测试+冒烟测试）
just doctor - 本地文件与数据库一致性检查（临时配置）

Postgres测试说明： 使用testcontainers自动启动Docker容器，无需手动配置数据库（需运行Docker）。

Testmon提示： 当无文件变更时，just testmon可能显示0测试，这表示未检测到受影响测试。

测试标记：

windows - Windows专属数据库优化
benchmark - 性能测试（默认不运行）
smoke - 快速MCP端到端测试

其他开发命令：

just install          # 安装开发依赖
just lint             # 代码规范检查
just typecheck        # 类型检查  
just format           # ruff代码格式化
just fast-check       # 快速开发循环（修复/格式化/类型检查+testmon+冒烟测试）
just doctor           # 本地一致性检查（临时配置）
just check            # 全质量检查
just migration "说明" # 创建数据库迁移

本地一致性检查：

basic-memory doctor   # 在临时项目中验证文件与数据库同步

完整命令列表参见justfile文件。

开源协议

AGPL-3.0

欢迎贡献代码，参见贡献指南了解本地环境配置和PR提交规范。

星标历史

Basic Machines倾情打造