Como Dar aos Agentes de IA Memória de Longo Prazo Usando o Obsidian

Na semana passada, me peguei explicando a estrutura do nosso serviço de autenticação para um agente de codificação pela terceira vez neste mês. A janela de contexto do Claude Code é grande o suficiente, mas qualquer sessão eventualmente termina. Uma nova execução no terminal — e o console não sabe mais nada sobre decisões arquiteturais, acordos da equipe ou tarefas da sprint.

Recentemente, encontrei o projeto obsidian- do desenvolvedor Brenno Ferrari. O autor adotou uma abordagem direta: se um agente precisa de memória de longo prazo, por que não torná-la um cofre regular do Obsidian?

O Que Está Dentro do Modelo

O projeto é uma estrutura de notas pronta para uso, um conjunto de hooks TypeScript e comandos CLI pré-construídos. Logo de início, o modelo funciona com Claude Code, Codex CLI, Gemini CLI e outros sistemas que podem ler regras de arquivos de instrução.

A ideia é que o agente lê e atualiza arquivos Markdown por conta própria. Quando uma sessão começa, um hook lê metas globais do arquivo brain/North Star.md, puxa a lista de tarefas ativas e passa essa fatia para a janela de contexto. Quando você informa ao agente sobre uma decisão tomada ou uma reunião que aconteceu, ele organiza os dados em pastas e os vincula a nomes de colegas ou projetos.

Como Funciona o Controle de Uso de Tokens

O principal problema com sistemas assim é o consumo de tokens. Se você enfiar toda a base de conhecimento no contexto a cada requisição, os limites vão se esgotar em algumas horas.

No obsidian-, isso é tratado por um esquema de carregamento em múltiplas camadas:

• Quando uma sessão começa, uma fatia de base é lida: metas, tarefas abertas, commits recentes e a lista de arquivos do cofre. Isso consome cerca de 20.000 tokens.
• Para busca semântica, o utilitário QMD é usado. Ele constrói embeddings vetoriais localmente e encontra os fragmentos relevantes quando o agente precisa de informações específicas.
• Quando mensagens são enviadas, o script determina o tipo de dado (incidente, reunião, decisão arquitetural) e passa uma dica de roteamento curta ao agente.
• Depois que os arquivos são escritos, um validador é executado para verificar a correção dos links wiki e parâmetros YAML.

Como É um Dia de Trabalho

De manhã você executa o comando /om-standup. O agente lê as mudanças recentes no git, cruza referências com a lista de tarefas e produz um resumo breve.

Após reuniões ou discussões no Slack, não há necessidade de preencher manualmente as estruturas de documentos. Basta alimentar o texto bruto ao agente:

/om-dump Обсудили с Сарой рефакторинг авторизации. Решили отложить миграцию на Redis до второго квартала. Сара похвалила архитектуру API.

Em resposta, o sistema faz quatro coisas automaticamente ao mesmo tempo:

1. Atualiza o arquivo de histórico de reuniões em org/people/Sarah Chen.md.
2. Cria uma entrada de decisão na pasta de decisões.
3. Registra elogios no modelo de atestado perf/Brag Doc.md.
4. Adiciona uma nova tarefa ao card do projeto ativo.

No final do dia, o comando /om-wrap-up verifica notas órfãs sem referências cruzadas e atualiza os índices.

Executando Tarefas em Segundo Plano via Sub-Agentes

Para operações pesadas, sub-agentes especializados são configurados dentro do modelo. Eles são executados em janelas de contexto isoladas para evitar poluir o histórico principal da conversa.

O repositório possui vários agentes pré-configurados:

• slack-
• cross-linker busca links wiki quebrados e notas esquecidas em todo o cofre.
• brag-
• people-

Compilação e Execução

Você pode fazer deploy do cofre via o gerenciador de modelos ShardMind ou simplesmente clonando o repositório.

npm install -g shardmind
mkdir my-vault && cd my-vault
shardmind install github:breferrari/obsidian-mind

O comando de configuração vai pedir para você inserir seu nome, nome da empresa e metas principais. Depois disso, você só precisará seguir alguns passos simples:

1. Abra a pasta criada como um cofre no Obsidian.
2. Habilite o plugin Obsidian CLI nas configurações do aplicativo (requer Obsidian 1.12+).
3. Execute o agente CLI diretamente do diretório do cofre.

Para busca completa, você também deve instalar a ferramenta de busca vetorial QMD:

npm install -g @tobilu/qmd
node --experimental-strip-types .scripts/qmd-bootstrap.ts

Sem o QMD, o sistema continuará funcionando via grep e a busca nativa do Obsidian, embora a precisão das respostas a perguntas abstratas diminua ligeiramente.

Para Quem Este Projeto É

O modelo será útil para desenvolvedores que usam ativamente agentes de IA baseados em CLI e já mantêm ou planejam manter notas no Obsidian. O valor principal aqui está nas regras bem pensadas para vincular documentos entre si.

Uma coisa a ser observada é a dependência do Node.js versão 22+ com a flag --experimental-strip-types para executar scripts TypeScript sem pré-compilação. Se essa flag for renomeada em futuras versões do Node.js, você precisará atualizar as configurações do hook. No entanto, o projeto fornece uma excelente base pronta para uso e elimina a necessidade de construir esse tipo de estrutura do zero.