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 хоста.

Извлечение Codex SessionStart было проверено в реальном времени от начала до конца с 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 редактирует распознанные шаблоны учетных данных перед автоматической записью тела/заголовка/тегов; неизвестные шаблоны и ручные правки остаются вашей ответственностью.
• Облачные функции — это явный исходящий трафик. По умолчанию всё работает локально. При включении облачного эмбеддера или LLM-судьи оставшийся отредактированный текст отправляется этому провайдеру.
• Проект находится в стадии бета-тестирования. Для автономного использования требуется Python 3.11+, и первая загрузка локальной модели может занять время. Опубликованные доказательства извлечения наиболее убедительны для диалоговой памяти, а не как универсальное заявление о поиске по коду.
• Фоновое поведение зависит от хоста. Приведённая выше матрица сделана намеренно: Cursor и Antigravity полагаются на захват области; универсальные MCP-хосты могут предоставлять инструменты без хуков жизненного цикла.
• Автоматизация зависит от платформы. Управляемое планирование нацелено на launchd в macOS и пользовательский 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.