Basic Memory — постоянная память ИИ-агентов на обычных Markdown-файлах

Basic Memory — это хранилище знаний, где ИИ-агент и человек пишут в одни и те же Markdown-файлы. Вы объясняете модели проект один раз. Дальше она читает ваши заметки, дополняет их и строит из них граф знаний, по которому можно переходить по ссылкам. Всё лежит на вашем диске, доступ идёт через MCP — подойдёт Claude, Codex, Cursor, VS Code, ChatGPT и Obsidian.

Лицензия AGPL-3.0, язык — Python 3.12+, около 4,3 тысяч звёзд.

Какую проблему решает

Разговор с LLM заканчивается вместе с окном чата. Вы задаёте вопрос, получаете ответ, и всё забыто. Привычные обходные пути тоже имеют потолок:

Basic Memory идёт простым путём: знание лежит в обычных Markdown-файлах. Их читает и пишет и человек, и модель. Источник истины всегда ваши файлы.

Что внутри

• Локально. Обычный текст на вашем диске. Его можно открыть в любом редакторе.
• Двусторонняя работа. Агент и человек пишут в одни и те же файлы, синхронизация держит их в согласии.
• Настоящий граф знаний. Наблюдения и вики-ссылки складываются в связный контекст.
• Семантический поиск. Ищет заметки по смыслу, а не только по словам. Есть опциональное переранжирование через кросс-энкодер.
• MCP из коробки. Работает с любым клиентом и IDE, которые говорят на MCP.
• Постепенное открытие инструментов. У каждого MCP-инструмента есть пометки: читает или пишет, разрушает ли данные, можно ли повторять. Агент выбирает нужный инструмент сразу, а не перебирает наугад.
• Облако по желанию. Синхронизация между устройствами есть, но она не обязательна.

Установка

Нужен Python через uv:

uv tool install basic-memory --prerelease=allow

Флаг --prerelease=allow обязателен. Basic Memory 0.23 зависит от предрелизной версии FastMCP 4, а uv принимает такие зависимости только с этим флагом. Без него uv молча поставит более старую версию. Тот же флаг нужен на всех командах uvx и uv tool upgrade.

Для развёртываний на Postgres, где векторы хранятся в Milvus, есть отдельный набор дополнений:

uv tool install "basic-memory[milvus]" --prerelease=allow

Подключение к клиентам

Для Claude Code одна команда:

claude mcp add basic-memory -- uvx --prerelease=allow basic-memory mcp

Для Codex CLI — запись в ~/.codex/config.toml:

[mcp_servers.basic-memory]
command = "uvx"
args = ["--prerelease=allow", "basic-memory", "mcp"]

Для Cursor — блок в .cursor/mcp.json или в ~/.cursor/mcp.json:

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

Для VS Code — то же самое в пользовательских настройках:

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

Для Claude Desktop правьте ~/Library/Application Support/Claude/claude_desktop_config.json. После перезапуска заметки лежат в ~/basic-memory.

С Obsidian настройка не нужна. Откройте в нём папку ~/basic-memory — те же вики-ссылки, тот же Markdown, что пишет ИИ. Правьте любую сторону, синхронизация разберётся.

Поддерживаются как stdio, так и https-транспорт. Полный список клиентов и способов подключения — в README репозитория.

Формат заметки

Каждый файл — это сущность (Entity). У сущности есть наблюдения (Observations) — факты о ней — и связи (Relations) — ссылки на другие сущности. Это вся грамматика, больше ничего учить не нужно.

Фронтматер:

---
title: <название сущности>
type: note
permalink: <адресный слаг>
tags: [необязательно, список]
---

Наблюдения. Категория пишется в квадратных скобках, тег — с решётки, дополнительный контекст — в скобках:

- [method] Пуровер даёт больше прозрачности вкуса
- [tip] Для V60 молоть на средне-мелкой фракции #brewing
- [fact] Светлая обжарка содержит больше кофеина, чем тёмная
- [question] Как температура влияет на извлечение веществ?

Связи. Тип связи одним словом, многословный — в кавычках:

- pairs_well_with [[Chocolate Desserts]]
- grown_in [[Ethiopia]]
- requires [[Burr Grinder]]
- "pairs well with" [[Dark Chocolate]]

Голые - [[Цель]] и прозаические - Стоит посмотреть [[Цель]] попадают в индекс как links_to.

Как это выглядит на практике

Вы обсуждаете с моделью кофе. Потом просите сохранить выводы. В папке проекта появляется файл:

---
title: Coffee Brewing Methods
permalink: coffee-brewing-methods
tags: [coffee, brewing]
---

# Coffee Brewing Methods

## Observations
- [method] Пуровер лучше френч-пресса показывает тонкие вкусы
- [technique] Вода при 205°F (96°C) извлекает вещества лучше всего
- [principle] Свежемолотые зёрна сохраняют ароматику

## Relations
- relates_to [[Coffee Bean Origins]]
- requires [[Proper Grinding Technique]]
- affects [[Flavor Extraction]]

В следующей сессии модель подхватывает разговор. Она идёт по связям и достаёт то, что вы уже знали про эфиопские зёрна и жерновая кофемолка, и продолжает с этого места, а не с нуля. Вы видите те же файлы в Obsidian. Правите руками — ИИ видит ваши правки. Истина всегда в файлах.

MCP-инструменты

Инструменты разложены по назначению:

По умолчанию инструменты отдают текст. Для машинного вывода передайте output_format="json".

Облако

Платная версия — тот же продукт на тех же файлах. Разница в том, что серверную часть и синхронизацию берёт на себя автор. $15 в месяц, цена зафиксирована на весь срок подписки, 7 дней бесплатно.

При отмене подписки заметки можно выгрузить обратно в Markdown — те же файлы, тот же формат, те же вики-ссылки. Привязки к сервису нет. Маршрутизация делается по проектам: часть проектов можно держать в облаке, часть локально.

Расширения для агентов

Репозиторий — общий источник всех пакетов.

Плагин для Claude Code. Он связывает рабочую память Claude с хранилищем: брифинги на старте сессии, контрольные точки перед сжатием контекста и команды /basic-memory:bm-setup, :remember, :share, :status. Сначала подключите MCP-сервер — хуки плагина вызывают его. Потом:

bm install claude-code

Ключ --scope project записывает и маркетплейс, и плагин в настройки репозитория. Исходники — в каталоге plugins/claude-code.

Общие навыки. Файлы SKILL.md лежат в каталоге skills. Если ваш Skills CLI умеет брать подкаталоги репозитория:

npx skills add basicmachines-co/basic-memory/skills -g

Для Claude и ChatGPT есть готовые архивы в релизе skills-latest, подробности — в skills/README.md.

Hermes и OpenClaw. Плагины публикуются из того же дерева исходников:

hermes plugins install basicmachines-co/basic-memory/integrations/hermes
openclaw plugins install @basicmemory/openclaw-basic-memory

Что нового

• Автоматические обновления. Приложение само обновляется, если поставлено через uv tool или Homebrew. bm update запускает проверку вручную.
• Семантический векторный поиск. Гибридное ранжирование: полнотекстовый поиск плюс вектора, эмбеддинги через FastEmbed. Работает на SQLite и Postgres.
• Переранжирование. Второй проход по самым подходящим кандидатам через локальный кросс-энкодер FastEmbed или через LiteLLM. Выключено по умолчанию: добавляет задержку и скачивает модель при первом запуске.
• Система схем. schema_infer, schema_validate, schema_diff выводят структуру базы знаний, проверяют её и показывают разницу.
• Умное редактирование. edit_note с добавлением в начало или конец сам создаёт заметку, если её нет. write_note защищает от случайной перезаписи.
• Богатые результаты поиска. В выдачу попадает сам текст совпавшего фрагмента, а не только ссылка.
• Пометки инструментов. У каждого MCP-инструмента есть подсказки: readOnlyHint, destructiveHint, idempotentHint, openWorldHint.
• Переработка CLI. Вывод --json для скриптов, команды с учётом рабочих пространств и панель проектов в духе htop.

Переранживание и его настройка

По умолчанию переранжирование выключено. Локальный вариант:

export BASIC_MEMORY_RERANKER_ENABLED=true

Модель по умолчанию — jinaai/jina-reranker-v1-tiny-en. Вариант через LiteLLM:

export BASIC_MEMORY_RERANKER_ENABLED=true
export BASIC_MEMORY_RERANKER_PROVIDER=litellm
export BASIC_MEMORY_RERANKER_MODEL=cohere/rerank-v3.5
export COHERE_API_KEY=...

Если провайдер падает, инструмент сразу останавливается, а не молча возвращает результаты без переранжирования. Настройка описана в руководстве по семантическому поиску.

CLI

# Проекты
basic-memory project list
basic-memory project add research ~/research

# Настройки
basic-memory config list
basic-memory config set cli_output_style plain

# Состояние и обслуживание
basic-memory status
basic-memory doctor          # сверка файлов и базы
basic-memory update

# Импорт
basic-memory import claude conversations
basic-memory import chatgpt

По умолчанию CLI пишет в файл ~/.basic-memory/basic-memory.log с ротацией 10 МБ и хранением 10 дней. MCP-сервер пишет только в файл, потому что вывод в stdout испортил бы JSON-RPC.

Задать уровень детализации и посмотреть лог:

BASIC_MEMORY_LOG_LEVEL=DEBUG basic-memory reindex
tail -f ~/.basic-memory/basic-memory.log

Телеметрия

Собирается минимум: показы рекламы облака, попытки входа и их результаты. Не собираются содержимое файлов, названия заметок, данные базы знаний, персональные данные и IP-адреса. События уходят в открытый Umami Cloud в фоне. Отключается переменной BASIC_MEMORY_NO_PROMOS=1.

Разработка

Поддерживаются SQLite — по умолчанию, быстро, без Docker — и Postgres через testcontainers.

just install
just test-sqlite
just lint
just typecheck
just check
just migration "msg"

Полный список команд — в justfile. Правила работы с кодом описаны в CONTRIBUTING.md, изменения — в CHANGELOG.md. Код распространяется под AGPL-3.0.