agentcairn

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

Веб-сайт · PyPI · Компаньон для Obsidian · Бенчмарки

Камнем отмечают тропу для тех, кто идёт следом. agentcairn делает то же самое для кодирующих агентов: он захватывает долговечный контекст из используемых вами инструментов, сохраняет его в виде проверяемого Markdown с указанием происхождения и возвращает только наиболее релевантные фрагменты, когда другому агенту они нужны.

Доказательство, которое можно проверить

Память не скрыта за админ-консолью или облачной базой данных. Отдельный компаньон agentcairn-obsidian читает те же файлы Markdown, что и агенты, и показывает происхождение, актуальность, важность, замену и ссылки related:.

_{Реальное хранилище agentcairn в Obsidian. Список — это представление над файлами, а не второе хранилище памяти.}

Снимок для самопроверки · 2026-07-15. При 417 локальных обращениях хранилище мейнтейнера возвращало контекст в 262× smaller раз меньше, чем полная загрузка хранилища каждый раз, — по оценкам, 136.6M tokens of full-vault context avoided в сумме. Подсчёт токенов использует примерно четыре символа на токен. Это не экономия на оплачиваемых токенах, и agentcairn не отправляет телеметрию.

Установка

Самый короткий путь — плагин первого класса. Он включает MCP-сервер, навык памяти и специфичные для хоста фоновые хуки — отдельная установка пакета agentcairn не нужна. Плагин запускается через uvx, поэтому сначала установите uv, если uvx --version ещё не доступен.

Claude Code

claude plugin marketplace add ccf/agentcairn
claude plugin install agentcairn@agentcairn

Claude Code получает пошаговое вспоминание в рамках проекта, захват сессии/компактации и команды /agentcairn:recall, /agentcairn:remember, /agentcairn:memory, /agentcairn:savings и /agentcairn:ingest.

Codex

codex plugin marketplace add ccf/agentcairn
codex plugin add agentcairn@agentcairn

Codex получает встроенные MCP-инструменты и навык памяти, вспоминание SessionStart с живой проверкой и захват SessionEnd с cairn sweep в качестве внешнего резерва.

Настройка с помощью агента

Уже используете skills.sh или рабочий процесс find-skills? Установите публичного помощника по настройке:

npx skills add ccf/agentcairn --skill agentcairn-setup -g

Затем спросите своего агента: Use $agentcairn-setup to preview, install, and verify AgentCairn for this coding agent.

Это устанавливает только руководство по настройке — не среду выполнения AgentCairn, MCP-сервер, плагин или хуки. Помощник делегирует эти изменения нативному установщику AgentCairn с предварительным просмотром и проверяет результат интеграции. Команды плагинов Claude Code и Codex выше остаются самым коротким путём.

Хранилище по умолчанию — ~/agentcairn и создаётся при первом использовании. В новом пустом хранилище пока нечего вспоминать, поэтому проверьте весь цикл явно:

You   → Remember this durable fact: staging deploys use blue-green.
Agent → written and indexed
You   → Recall the staging deploy strategy.
Agent → staging deploys use blue-green.  ↳ <memory permalink>

remember записывает заметку Markdown и запись индекса вместе, поэтому немедленное вспоминание — часть контракта. Первый локальный запуск может загрузить и прогреть настроенные модели эмбеддингов/реранкинга.

Контракт

Как это работает

• Захват: хуки хоста повышают оперативность; cairn sweep читает поддерживаемые хранилища транскриптов вне полосы как долговечный резерв. AgentCairn редактирует распознанные учётные данные, дедуплицирует, фильтрует по важности и дистиллирует перед автоматической записью в открытом виде.
• Согласование: первое чтение транзакционно синхронизирует индекс хранилища с Markdown. Неудачная пересборка сохраняет последний хороший кэш, а долговечные файлы остаются нетронутыми.
• Вспоминание: BM25 и семантические векторы объединяются с помощью Reciprocal Rank Fusion, затем опционально реранкируются. Сбои модели/провайдера видимо откатываются к BM25 с диагностикой, а не возвращают несовместимые векторы.
• Запоминание: MCP-инструмент атомарно записывает заметку Markdown и обновляет индекс под одной блокировкой записи, делая успешное сохранение немедленно вспоминаемым.

Создано для доверия

• Локально по умолчанию. FastEmbed работает локально, MCP-сервер использует stdio, нет обязательного демона или внешней базы данных и нет телеметрии.
• Чёткие границы. Синхронизированное хранилище содержит Markdown; по умолчанию пересобираемый индекс .duckdb находится вне его. Симлинки хранилища, выходящие за настроенный корень, отклоняются.
• Коррекции с учётом времени. valid_from, valid_until и superseded_by сохраняют старые данные видимыми, но текущие факты ранжируются первыми.
• Детерминированный граф. [[wikilinks]] и опциональные соседи cairn link создают нативный для Obsidian граф без просьбы к LLM выдумывать сущности.
• Вспоминание с учётом проекта. Текущий проект усиливается по умолчанию; межпроектные результаты остаются доступными и помечаются. Автоматическое вспоминание ограничено проектом, если вы явно не выберете все проекты.

Поддерживаемые агенты

Каждый хост разрешает одно настроенное хранилище. cairn install предпросматривает обнаруженные хосты без записи. Записи конфигурации MCP делаются с резервным копированием и сохраняют несвязанные серверы; установки через плагины делегируются собственному CLI хоста.

SessionStart в Codex был проверен вживую end-to-end с agentcairn 0.24.2 / плагином 0.1.2. Установленная диспетчеризация команд SessionEnd и отсоединённая очистка проходят точные проверки обработчиков; cairn sweep остаётся внешним резервом захвата. См. интеграцию OpenCode и интеграцию Hermes для деталей их нативных жизненных циклов.

Прямое использование

Плагин — самый простой путь, но agentcairn также является автономным CLI и MCP-сервером по запросу. Автономные установки требуют Python 3.11+.

uv tool install agentcairn

cairn init ~/agentcairn
cairn sweep --vault ~/agentcairn
cairn recall "how did we fix the auth bug?" --vault ~/agentcairn
cairn doctor --vault ~/agentcairn

Возьмите память Claude Code с собой

Автопамять Claude Code может заполнить общее хранилище без изменения исходных файлов. Команда по умолчанию предпросматривает только текущий репозиторий; добавьте --apply, чтобы записать отредактированные заметки и обновить индекс.

cairn import claude-memory                         # preview; writes nothing
cairn import claude-memory --apply                 # import this repository
cairn import claude-memory --project ../other --apply

Однонаправленный импорт читает MEMORY.md и его тематические файлы Markdown — никогда CLAUDE.md или .claude/rules/. Импортированные заметки сохраняют происхождение Claude Code, проекта и исходного файла. Когда источник меняется, предыдущая версия остаётся проверяемой, но помечается как заменённая; когда он исчезает, его импортированная версия истекает. Небольшой реестр .agentcairn/native-memory/ сохраняет этот жизненный цикл без двойного индексирования исходного контента. Используйте --source <dir> для пользовательского, управляемого или переопределённого сессией каталога памяти Claude, или --no-reindex при пакетном импорте.

Предпочитаете эфемерный процесс:

uvx agentcairn                             # MCP server
uvx --from agentcairn cairn recall "..."  # CLI; plain `uvx cairn` is a different package

cairn schedule install --vault ~/agentcairn  # launchd on macOS / user crontab on Linux
cairn schedule status
cairn link --vault ~/agentcairn              # write deterministic related: neighbors
cairn reindex ~/agentcairn                   # rebuild the disposable cache
cairn savings                                # local context-efficiency estimate
cairn index-status --vault ~/agentcairn

cairn config --init
cairn config

auto_recall = true
auto_recall_k = 3
auto_recall_scope = "project"  # use "all" only as an explicit cross-project opt-in

Измеренные бенчмарки

Репозиторий содержит воспроизводимый с фиксированными версиями харнесс LongMemEval-S + LoCoMo. По умолчанию — локальный nomic-embed-text-v1.5 плюс кросс-энкодерный реранкер.

Контекст, возвращаемый при значении по умолчанию k=10, намного меньше полной индексированной истории:

Читайте цифры честно:

• Вспоминание при поиске — это не точность ответов на вопросы. Эти таблицы сравнивают контролируемые ветви поиска, а не качество ответов конечного пользователя или баллы лидерборда другого продукта.
• Подсчёт токенов использует эвристику примерно четырёх символов на токен. Сокращение сравнивает индексированный стог сена с возвращёнными фрагментами; это не экономия на оплачиваемых затратах.
• Усиление графа инертно на этих чат-корпусах, потому что в них нет нативного графа [[wikilink]]. Он предназначен для реальных взаимосвязанных хранилищ.
• Опциональный судья QA использует Anthropic, а не настройку GPT-4o из статей, поэтому результаты QA полезны для относительных абляций, а не для сравнения с опубликованными лидербордами.

Полные метрики, подборы эмбеддингов, измерения задержки, лицензии, команды и оговорки находятся в benchmarks/README.md.

Конфиденциальность и ограничения

• Хранилище — это открытый текст по замыслу, а не зашифрованное хранилище. AgentCairn редактирует распознанные шаблоны учетных данных перед автоматической записью body/title/tag; неизвестные шаблоны и ручные правки остаются вашей ответственностью.
• Файлы хранилища доступны только владельцу (0600/0700). Поскольку хранилище — открытый текст, а редактирование — это best-effort, режим файла фактически является единственным контролем доступа. Настройки с общей группой (например, два Docker-контейнера в одной группе, но с разными UID) требуют группового доступа, поэтому vault_group_writable = true расширяет новые заметки и каталоги хранилища до 0660/0770. Это осознанный выбор: на macOS основная группа каждого локального пользователя — staff, поэтому групповое чтение по умолчанию открыло бы ваши воспоминания другим учетным записям на машине. Этот параметр никогда не расширяет доступ за пределы хранилища — индекс, реестры, файлы блокировок и ~/.agentcairn/config.toml остаются приватными.
• Облачные функции — это явный исходящий трафик. По умолчанию все остается локальным. Включение облачного эмбеддера или LLM-судьи отправляет оставшийся отредактированный текст этому провайдеру.
• Проект находится в стадии бета. Для автономного использования требуется Python 3.11+, и первая загрузка локальной модели может занять время. Опубликованные доказательства поиска наиболее сильны для разговорной памяти, а не для универсального поиска по коду.
• Поведение в окружении зависит от хоста. Матрица выше намеренна: Cursor и Antigravity полагаются на захват sweep; универсальные MCP-хосты могут предоставлять инструменты без хуков жизненного цикла.
• Автоматизация зависит от платформы. Управляемое планирование нацелено на macOS launchd и пользовательский crontab Linux; в других средах используйте собственный планировщик.

Разработка

agentcairn использует uv исключительно для управления зависимостями и инструментами.

uv sync
uv run pre-commit install

uv run pytest
uv run ruff format .
uv run ruff check --fix .
uv run pre-commit run --all-files

Запустите офлайн-регрессию бенчмарка без ключей API:

uv run pytest benchmarks/tests/

Лицензия

Apache License 2.0 — разрешительная, с явным патентным грантом. Copyright © 2026 Charles C. Figueiredo.