agentcairn

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

Website · PyPI · Companheiro Obsidian · Benchmarks

Um marco (cairn) sinaliza o caminho para quem vier depois. agentcairn faz isso por 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 precisar delas.

Prova que você pode inspecionar

A memória não fica escondida atrás de um console administrativo ou banco de dados hospedado. O companheiro 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.}

Snapshot de dogfooding · 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—uma estimativa de 136.6M tokens of full-vault context avoided no total. As contagens de tokens usam aproximadamente quatro caracteres por token. Isso não é economia de tokens cobrados, e o agentcairn não envia telemetria.

Instalação

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

Claude Code

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

O Claude Code recebe recuperação por turno com escopo de projeto, 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 recebe as ferramentas MCP agrupadas e a habilidade de memória, recuperação SessionStart verificada ao vivo e captura SessionEnd com cairn sweep como proteção 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 orientação de configuração—não o runtime do 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 não tem nada útil para recuperar ainda, então prove o loop inteiro 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 escreve a nota Markdown e a entrada de índice juntas, então a recuperação imediata faz parte do contrato. A primeira execução local pode baixar e aquecer os modelos de embedding/reranking configurados.

O contrato

Como funciona

• Captura: ganchos de host melhoram a imediatez; cairn sweep lê armazenamentos de transcrição suportados fora de banda como proteção durável. O AgentCairn redige credenciais reconhecidas, deduplica, aplica portões de importância e destila antes de suas escritas automatizadas em texto puro.
• Reconciliação: a primeira transação de leitura sincroniza o índice com escopo de cofre com o Markdown. Uma reconstrução falha preserva o último cache bom e os arquivos duráveis permanecem intocados.
• Recuperação: vetores BM25 e semânticos são fundidos com Reciprocal Rank Fusion e, opcionalmente, reranqueados. Falhas de modelo/provedor caem visivelmente para BM25 com diagnósticos em vez de retornar vetores incompatíveis.
• Lembrança: a ferramenta MCP escreve atomicamente uma nota Markdown e atualiza o índice sob um único bloqueio de escrita, tornando um salvamento bem-sucedido imediatamente recuperável.

Projetado para confiança

• Local por padrão. FastEmbed roda localmente, o servidor MCP usa stdio, não há daemon ou banco de dados externo obrigatório e não há telemetria.
• Fronteiras claras. O cofre sincronizado contém Markdown; por padrão, o índice .duckdb reconstruível fica fora dele. Symlinks de cofre que escapam da raiz configurada são rejeitados.
• Correções cientes do tempo. valid_from, valid_until e superseded_by mantêm evidência antiga visível enquanto fazem fatos atuais rankearem 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 entre projetos 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

Todo host resolve o mesmo cofre configurado. cairn install pré-visualiza hosts detectados sem escrever. As escritas de configuração MCP são backup-first e preservam servidores não relacionados; instalações de plugin-host delegam ao 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 destacada passam em sondas exatas de handler; cairn sweep permanece como proteção de captura fora de banda. Veja a integração OpenCode e a integração Hermes para detalhes de ciclo de vida nativos.

Usando diretamente

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

Traga a memória do Claude Code com você

A auto-memória 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 escrever 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 do Claude personalizado, gerenciado ou com sobreposição de sessão, ou --no-reindex ao agrupar importações.

Prefere 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 reproduzível e com versão fixada. O padrão é nomic-embed-text-v1.5 local mais o reranker de cross-encoder.

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

Leia os números honestamente:

• Recall de recuperação 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 chunks retornados; não é economia de custo cobrado.
• O boost de grafo é inerte nesses corpora de chat porque 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 comparações de leaderboard publicado.

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

Privacidade e limites

• O vault é texto puro por design, não armazenamento criptografado. O AgentCairn remove padrões de credenciais reconhecidos antes de suas gravações automáticas de corpo/título/tag; padrões desconhecidos e edições manuais permanecem sob sua responsabilidade.
• Os arquivos do vault são somente do proprietário (0600/0700). Como o vault é texto puro e a remoção é melhor esforço, o modo de arquivo é efetivamente seu único controle de acesso. Configurações de GID compartilhado (ex.: dois contêineres Docker no mesmo grupo, mas com UIDs diferentes) precisam de acesso de grupo, então vault_group_writable = true amplia novas notas e diretórios do vault para 0660/0770. É opt-in de propósito: no macOS, o grupo primário de cada usuário local é staff, então um padrão legível por grupo exporia suas memórias a outras contas na máquina. O controle nunca amplia nada fora do vault — o índice, livros-razão, arquivos de bloqueio e ~/.agentcairn/config.toml permanecem privados.
• Recursos de nuvem são egresso explícito. O padrão permanece local. Optar por um embedder de nuvem ou juiz de LLM envia o texto restante removido 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 da captura de varredura; hosts MCP genéricos podem expor ferramentas sem ganchos de ciclo de vida.
• A automação é específica da plataforma. O agendamento gerenciado tem como alvo o launchd do macOS e o crontab do usuário 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 o benchmark de regressão offline sem chaves de API:

uv run pytest benchmarks/tests/

Licença

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