Basic Memory

Basic Memory 让你通过与大型语言模型 (LLM)（如 Claude）的自然对话来构建持久的知识，同时将所有内容保存在你电脑上的简单 Markdown 文件中。它使用模型上下文协议 (MCP) 来使任何兼容的 LLM 能够读取和写入你的本地知识库。

• 网站：https://basicmachines.co
• 文档：https://memory.basicmachines.co

从你上次离开的地方继续你的对话

• AI 助手可以在新的对话中从本地文件加载上下文
• 笔记会实时保存为本地 Markdown 文件
• 无需项目知识或特殊提示

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

快速开始

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

# 配置 Claude Desktop（编辑 ~/Library/Application Support/Claude/claude_desktop_config.json）
# 将此添加到你的配置中：
{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "basic-memory",
        "mcp"
      ]
    }
  }
}
# 现在在 Claude Desktop 中，你可以：
# - 使用“Create a note about coffee brewing methods”编写笔记
# - 使用“What do I know about pour over coffee?”阅读笔记
# - 使用“Find information about Ethiopian beans”搜索

你可以通过 ~/basic-memory（默认目录位置）中的文件查看共享上下文。

通过 Smithery 进行替代安装

你可以使用 Smithery 自动配置 Basic Memory 以用于 Claude Desktop：

npx -y @smithery/cli install @basicmachines-co/basic-memory --client claude

这会安装和配置 Basic Memory，而无需手动编辑 Claude Desktop 配置文件。Smithery 服务器托管 MCP 服务器组件，而你的数据仍然以 Markdown 文件的形式本地存储。

Glama.ai

<a href="https://glama.ai/mcp/servers/o90kttu9ym"> <img width="380" height="200" src="https://glama.ai/mcp/servers/o90kttu9ym/badge" alt="basic-memory MCP server" /> </a>

为什么选择 Basic Memory？

大多数 LLM 交互都是短暂的 - 你提出一个问题，得到一个答案，然后一切都被遗忘。每次对话都以全新的方式开始，没有来自先前对话的上下文或知识。当前解决方法存在局限性：

• 聊天记录捕获对话，但不是结构化知识
• RAG 系统可以查询文档，但不允许 LLM 写回
• 向量数据库需要复杂的设置，并且通常位于云端
• 知识图通常需要专门的工具来维护

Basic Memory 通过一种简单的方法解决了这些问题：结构化的 Markdown 文件，人类和 LLM 都可以读取和写入。主要优点：

• 本地优先： 所有知识都保留在你控制的文件中
• 双向： 你和 LLM 都读取和写入相同的文件
• 结构化但简单： 使用熟悉的 Markdown 和语义模式
• 可遍历的知识图： LLM 可以跟踪主题之间的链接
• 标准格式： 适用于现有的编辑器，如 Obsidian
• 轻量级基础设施： 只是本地文件，索引在本地 SQLite 数据库中

使用 Basic Memory，你可以：

• 进行基于先前知识的对话
• 在自然对话期间创建结构化笔记
• 与 LLM 进行记住你之前讨论过的内容的对话
• 在语义上导航你的知识图
• 将所有内容保存在本地并由你控制
• 使用熟悉的工具（如 Obsidian）查看和编辑笔记
• 构建一个随着时间推移而增长的个人知识库

实际工作原理

假设你正在探索咖啡冲泡方法并想记录你的知识。以下是它的工作原理：

1. 首先正常聊天：

我一直在尝试不同的咖啡冲泡方法。我学到的关键知识：

- 相比法压壶，手冲能带来更清晰的风味
- 水温至关重要 - 205°F 左右似乎是最好的
- 新鲜研磨的咖啡豆会产生巨大的差异

... 继续对话。

2. 要求 LLM 帮助构建此知识：

"让我们写一篇关于咖啡冲泡方法的笔记。"

LLM 在你的系统上创建一个新的 Markdown 文件（你可以在 Obsidian 或你的编辑器中立即看到）：

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

# 咖啡冲泡方法

## 观察

- [方法] 手冲提供更清晰的风味，并突出细微的风味
- [技术] 205°F (96°C) 的水温提取最佳化合物
- [原理] 新鲜研磨的咖啡豆保留香气和风味

## 关系

- relates_to [[咖啡豆产地]]
- requires [[适当的研磨技术]]
- affects [[风味提取]]

该笔记嵌入了语义内容，并通过简单的 Markdown 格式链接到其他主题。

3. 你可以在当前项目目录（默认为 ~/$HOME/basic-memory）中实时在你的计算机上看到此文件。

• 默认情况下，v0.12.0 版本启用了实时同步

4. 在与 LLM 的聊天中，你可以引用一个主题：

查看 `coffee-brewing-methods` 以获取有关手冲咖啡的上下文

LLM 现在可以从知识图中构建丰富的上下文。例如：

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

遵循关系 'requires [[适当的研磨技术]]'：
- 刀片式研磨机与毛刺研磨机的比较
- 针对不同方法的研磨尺寸建议
- 一致的颗粒尺寸对提取的影响

每个相关文档都可以带来更多上下文，从而构建对你的知识库的丰富语义理解。

这创建了一个双向流程，其中：

• 人类编写和编辑 Markdown 文件
• LLM 通过 MCP 协议读取和写入
• 同步使一切保持一致
• 所有知识都保留在本地文件中。

技术实现

在底层，Basic Memory：

1. 将所有内容存储在 Markdown 文件中
2. 使用 SQLite 数据库进行搜索和索引
3. 从简单的 Markdown 模式中提取语义含义
   • 文件变成 Entity 对象
   • 每个 Entity 都可以有 Observations，或与之相关的事实
   • Relations 将实体连接在一起以形成知识图
4. 维护从文件派生的本地知识图
5. 提供文件和知识图之间的双向同步
6. 实现模型上下文协议 (MCP) 以进行 AI 集成
7. 公开允许 AI 助手遍历和操作知识图的工具
8. 使用 memory:// URL 在工具和对话中引用实体

文件格式只是带有简单标记的 Markdown：

每个 Markdown 文件都有：

Frontmatter

title: <实体标题>
type: <实体类型>（例如，笔记）
permalink: <一个 uri slug>

- <可选元数据>（例如标签）

观察

观察是关于主题的事实。 可以通过创建一个具有特殊格式的 Markdown 列表来添加它们，该格式可以使用“#”字符引用 category、tags 和可选的 context。

观察 Markdown 格式：

- [category] 内容 #tag (可选上下文)

观察示例：

- [方法] 相比法压壶，手冲提取更多的花香
- [提示] 手冲的研磨尺寸应为中等偏细 #冲泡
- [偏好] 埃塞俄比亚咖啡豆具有明亮的水果风味（尤其是来自耶加雪菲的咖啡豆）
- [事实] 浅烘焙通常比深烘焙含有更多的咖啡因
- [实验] 尝试了 1:15 的咖啡与水的比例，效果很好
- [资源] James Hoffman 在 YouTube 上的 V60 技术非常出色
- [问题] 水温是否会以不同的方式影响不同化合物的提取？
- [笔记] 我最喜欢的当地商店使用 30 秒的闷蒸时间

关系

关系是指向其他主题的链接。它们定义了实体如何在知识图中连接。

Markdown 格式：

- relation_type [[WikiLink]] (可选上下文)

关系示例：

- pairs_well_with [[巧克力甜点]]
- grown_in [[埃塞俄比亚]]
- contrasts_with [[茶冲泡方法]]
- requires [[毛刺研磨机]]
- improves_with [[新鲜咖啡豆]]
- relates_to [[早晨例行程序]]
- inspired_by [[日本咖啡文化]]
- documented_in [[咖啡日记]]

与 VS Code 一起使用

对于一键安装，请单击下面的安装按钮之一...

你可以将 Basic Memory 与 VS Code 结合使用，以便在编码时轻松检索和存储信息。单击上面的安装按钮进行一键设置，或按照下面的手动安装说明进行操作。

手动安装

将以下 JSON 块添加到 VS Code 中的用户设置 (JSON) 文件中。你可以通过按 Ctrl + Shift + P 并键入 Preferences: Open User Settings (JSON) 来执行此操作。

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

或者，你可以将其添加到工作区中名为 .vscode/mcp.json 的文件中。这将允许你与他人共享配置。

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

与 Claude Desktop 一起使用

Basic Memory 是使用 MCP（模型上下文协议）构建的，并且可以与 Claude 桌面应用程序 (https://claude.ai/) 一起使用：

1. 配置 Claude Desktop 以使用 Basic Memory：

编辑你的 MCP 配置文件（通常位于 OS X 的 ~/Library/Application Support/Claude/claude_desktop_config.json）：

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

如果你想使用特定的项目（请参阅 多个项目），请更新你的 Claude Desktop 配置：

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

2. 同步你的知识：

如果你进行手动编辑，Basic Memory 将实时同步项目中的文件。

3. 在 Claude Desktop 中，LLM 现在可以使用这些工具：

write_note(title, content, folder, tags) - 创建或更新笔记
read_note(identifier, page, page_size) - 按标题或永久链接读取笔记
build_context(url, depth, timeframe) - 通过 memory:// URL 导航知识图
search_notes(query, page, page_size) - 在你的知识库中搜索
recent_activity(type, depth, timeframe) - 查找最近更新的信息
canvas(nodes, edges, title, folder) - 生成知识可视化

5. 要尝试的示例提示：

"Create a note about our project architecture decisions"
"Find information about JWT authentication in my notes"
"Create a canvas visualization of my project components"
"Read my notes on the authentication system"
"What have I been working on in the past week?"

更多信息

请参阅文档以获取更多信息，包括：

• 完整用户指南
• CLI 工具
• 管理多个项目
• 从 OpenAI/Claude 项目导入数据

许可证

AGPL-3.0

欢迎贡献。请参阅贡献指南，以获取有关在本地设置项目和提交 PR 的信息。

Star 历史

<a href="https://www.star-history.com/#basicmachines-co/basic-memory&Date"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=basicmachines-co/basic-memory&type=Date&theme=dark" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=basicmachines-co/basic-memory&type=Date" /> <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=basicmachines-co/basic-memory&type=Date" /> </picture> </a>

由 Basic Machines 用 ♥️ 构建