agentcairn

Uma memória durável entre agentes de codificação compatíveis.
Seu cofre Markdown é canônico. DuckDB é o cache de recuperação substituível.

Website · PyPI · Complemento Obsidian · Benchmarks

Um marco de pedras (cairn) marca a trilha para quem vem depois. O agentcairn faz isso para agentes de codificação: captura contexto durável das ferramentas que você usa, armazena como Markdown inspecionável com proveniência e recupera apenas as peças mais relevantes quando outro agente precisa delas.

Prova que você pode inspecionar

A memória não está escondida atrás de um console de administração ou banco de dados hospedado. O complemento separado agentcairn-obsidian lê os mesmos arquivos Markdown que os agentes e expõe proveniência, atualidade, importância, substituição e links related:.

_{Um cofre agentcairn real no Obsidian. A lista é uma visão sobre os arquivos—não um segundo armazenamento de memória.}

Instantâneo do dogfood · 2026-07-15. Em 417 recuperações locais, o cofre do mantenedor retornou contexto sobre 262× smaller do que carregar o cofre inteiro a cada vez—um total estimado de 136.6M tokens of full-vault context avoided. Contagens de tokens usam aproximadamente quatro caracteres por token. Isso não é economia de tokens faturados, e o agentcairn não envia telemetria.

Instalar

O caminho mais curto é um plugin de primeira classe. Ele agrupa o servidor MCP, a habilidade de memória e os ganchos ambientes específicos do host—sem instalação separada do pacote agentcairn. O plugin é iniciado através do uvx, então instale o uv primeiro se o uvx --version ainda não estiver disponível.

Claude Code

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

O Claude Code obtém recuperação com escopo de projeto por turno, captura de sessão/compactação e os comandos /agentcairn:recall, /agentcairn:remember, /agentcairn:memory, /agentcairn:savings e /agentcairn:ingest.

Codex

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

O Codex obtém as ferramentas MCP e habilidade de memória agrupadas, recuperação SessionStart verificada ao vivo e captura SessionEnd com cairn sweep como o apoio fora de banda.

Configuração assistida por agente

Já usa skills.sh ou um fluxo de trabalho find-skills? Instale o assistente de configuração público:

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

Então pergunte ao seu agente: Use $agentcairn-setup to preview, install, and verify AgentCairn for this coding agent.

Isso instala apenas a orientação de configuração—não o runtime AgentCairn, servidor MCP, plugin ou ganchos. O assistente delega essas mudanças ao instalador nativo de pré-visualização do AgentCairn e verifica a integração resultante. Os comandos de plugin do Claude Code e Codex acima continuam sendo o caminho mais curto.

O cofre padrão é ~/agentcairn e é criado no primeiro uso. Um cofre novo e vazio ainda não tem nada útil para recuperar, então prove o ciclo completo explicitamente:

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 grava a nota Markdown e a entrada do índice juntos, então a recuperação imediata faz parte do contrato. A primeira execução local pode baixar e aquecer os modelos de incorporação/reclassificação configurados.

O contrato

Como funciona

• Captura: ganchos do host melhoram a imediação; cairn sweep lê armazenamentos de transcrição compatíveis fora de banda como o apoio durável. O AgentCairn redige credenciais reconhecidas, desduplica, filtra por importância e destila antes de suas gravações automatizadas em texto simples.
• Reconciliar: a primeira transação de leitura sincroniza o índice com escopo de cofre com o Markdown. Uma reconstrução com falha preserva o último bom cache e os arquivos duráveis permanecem intocados.
• Recuperar: BM25 e vetores semânticos são fundidos com Reciprocal Rank Fusion e, opcionalmente, reclassificados. Falhas de modelo/provedor voltam visivelmente para BM25 com diagnósticos em vez de retornar vetores incompatíveis.
• Lembrar: a ferramenta MCP grava atomicamente uma nota Markdown e atualiza o índice sob um bloqueio de escritor, tornando um salvamento bem-sucedido imediatamente recuperável.

Projetado para confiança

• Local por padrão. FastEmbed executa localmente, o servidor MCP usa stdio, não há daemon obrigatório ou banco de dados externo, e não há telemetria.
• Limites claros. O cofre sincronizado contém Markdown; por padrão, o índice reconstruível .duckdb fica fora dele. Symlinks do cofre que escapam da raiz configurada são rejeitados.
• Correções cientes do tempo. valid_from, valid_until e superseded_by mantêm evidências antigas visíveis enquanto fazem fatos atuais ranquearem primeiro.
• Grafo determinístico. [[wikilinks]] e vizinhos opcionais cairn link criam um grafo nativo do Obsidian sem pedir a um LLM para inventar entidades.
• Recuperação ciente do projeto. O projeto atual é impulsionado por padrão; resultados de projetos cruzados permanecem disponíveis e são rotulados. A recuperação automática tem escopo de projeto, a menos que você opte explicitamente por todos os projetos.

Agentes suportados

Cada host resolve o mesmo cofre configurado. cairn install pré-visualiza hosts detectados sem gravar. As gravações de configuração MCP são backup-first e preservam servidores não relacionados; as instalações de plugin-host delegam à CLI do próprio host.

O SessionStart do Codex foi verificado ao vivo de ponta a ponta com agentcairn 0.24.2 / plugin 0.1.2. O despacho de comando SessionEnd instalado e a varredura desanexada passam por sondas de manipulador exatas; cairn sweep permanece o apoio de captura fora de banda. Veja a integração OpenCode e integração Hermes para detalhes do ciclo de vida nativo.

Usando diretamente

O plugin é a rota mais fácil, mas o agentcairn também é uma CLI autônoma e servidor MCP sob demanda. Instalações autônomas requerem 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

Leve a memória do Claude Code com você

A memória automática do Claude Code pode semear o cofre compartilhado sem alterar seus arquivos de origem. O comando pré-visualiza apenas o repositório atual por padrão; adicione --apply para gravar as notas redigidas e atualizar o índice.

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

A importação unidirecional lê MEMORY.md e seus arquivos Markdown de tópico—nunca CLAUDE.md ou .claude/rules/. Notas importadas retêm proveniência do Claude Code, projeto e arquivo de origem. Quando uma fonte muda, a versão anterior permanece inspecionável, mas é substituída; quando uma desaparece, sua versão importada expira. Um pequeno registro .agentcairn/native-memory/ preserva esse ciclo de vida sem indexar o conteúdo da fonte duas vezes. Use --source <dir> para um diretório de memória Claude personalizado, gerenciado ou sobrescrito por sessão, ou --no-reindex ao importar em lote.

Prefira um processo efêmero:

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

Benchmarks medidos

O repositório inclui um harness LongMemEval-S + LoCoMo com revisão fixa e reproduzível. O padrão é nomic-embed-text-v1.5 local mais o reclassificador cross-encoder.

O contexto retornado no k=10 padrão é muito menor que o histórico indexado completo:

Leia os números honestamente:

• A recuperação de recall não é precisão de QA. Estas tabelas comparam braços de recuperação controlados, não a qualidade da resposta do usuário final ou a pontuação de leaderboard de outro produto.
• As contagens de tokens usam uma heurística de aproximadamente quatro caracteres por token. A redução compara o palheiro indexado com os fragmentos retornados; não é economia de custo faturada.
• O impulso do grafo é inerte nesses corpora de chat porque eles não contêm grafo [[wikilink]] nativo. Ele é projetado para cofres reais interligados.
• O juiz de QA opcional usa Anthropic em vez da configuração GPT-4o dos artigos, então esses resultados de QA são úteis para ablações relativas—não para comparações de leaderboard publicadas.

Métricas completas, varreduras de incorporação, medições de latência, licenças, comandos e ressalvas estão em benchmarks/README.md.

Privacidade e limites

• O cofre é texto simples por design, não armazenamento criptografado. O AgentCairn redige padrões de credenciais reconhecidos antes de suas gravações automatizadas de corpo/título/tags; padrões desconhecidos e edições manuais permanecem sob sua responsabilidade.
• Recursos de nuvem são saída explícita. O padrão permanece local. Optar por um incorporador de nuvem ou juiz LLM envia o texto redigido restante para esse provedor.
• O projeto está em beta. O uso independente requer Python 3.11+, e o primeiro carregamento do modelo local pode levar tempo. A evidência de recuperação publicada é mais forte para memória conversacional, não uma alegação universal de busca de código.
• O comportamento ambiente varia por host. A matriz acima é intencional: Cursor e Antigravity dependem de captura por varredura; hosts MCP genéricos podem expor ferramentas sem ganchos de ciclo de vida.
• A automação é específica da plataforma. O agendamento gerenciado visa launchd no macOS e crontab de usuário no Linux; use seu próprio agendador em outros lugares.

Desenvolvimento

agentcairn usa uv exclusivamente para gerenciamento de dependências e ferramentas.

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

Execute a regressão de benchmark offline sem chaves de API:

uv run pytest benchmarks/tests/

Licença

Licença Apache 2.0 — permissiva, com concessão explícita de patente. Copyright © 2026 Charles C. Figueiredo.