Jatobá Brain

O Jatobá Brain é uma camada de memória persistente para agentes de IA. Ele registra contexto operacional de projetos fora do modelo e o disponibiliza por MCP, HTTP e stdio.

Claude hoje. Codex amanhã. Outro modelo depois.

A memória pertence ao projeto, não a um modelo específico.

O que está implementado

• memória persistente isolada por workspace, projeto e repositório;

• PostgreSQL, pgvector opcional e fallback textual;

• tarefas, decisões, erros, soluções, checkpoints, sessões e mudanças Git;

• grafo estrutural por repositório com Graphify;

• Work Graph temporal para relações e timeline;

• recuperação híbrida limitada, rastreável e resiliente a fallbacks;

• handoff entre agentes e ownership transacional de tarefas;

• métricas, audit log, exportação de documentos e dashboard técnico;

• MCP Streamable HTTP autenticado e MCP stdio local.

Related MCP server: sill-ensoul

Arquitetura

Agente MCP
    |
    v
Jatobá Brain
    |
    +-- Semantic Memory: PostgreSQL + pgvector
    |     "O que é relevante?"
    |
    +-- Structural Memory: Graphify
    |     "Como o código está conectado?"
    |
    +-- Operational / Temporal Memory: Work Graph
    |     "O que aconteceu?"
    |
    +-- Hybrid Context Retriever
    |     "Qual contexto devemos entregar ao agente?"
    |
    +-- Multi-Agent Handoff
    |     "Quem continua o trabalho?"
    |
    +-- Observability + Dashboard
          "O que está acontecendo no Jatobá?"

A hierarquia de isolamento é:

WORKSPACE
  └── PROJECT
      └── REPOSITORY
          ├── TASK
          ├── MEMORY
          ├── DECISION
          ├── ERROR / SOLUTION
          ├── CHANGE / COMMIT
          ├── CHECKPOINT
          └── SESSION

Por padrão, recuperação usa o projeto selecionado. Busca entre projetos só ocorre com scope: "global" explícito. Um repositoryId é validado contra o projeto.

Veja a arquitetura detalhada, a integração Graphify e a documentação de clientes MCP.

Memória e contexto

Persistent Memory

remember persiste memórias com tipo, conteúdo, importância, metadados e vínculos opcionais com tarefa, sessão, repositório e agente. recall combina busca textual PostgreSQL, similaridade vetorial quando disponível, importância e recência.

Embeddings são opcionais. Se o endpoint estiver indisponível ou retornar vetor inválido, a memória continua consultável pela busca textual.

Structural Memory

graph_index gera explicitamente um snapshot Graphify para um repositório Git registrado. O Jatobá associa o snapshot ao commit usado na extração e informa READY, STALE, INDEXING ou ERROR.

O grafo fica separado por projeto/repositório e só subgrafos limitados são retornados. O graph.json inteiro nunca é enviado ao agente. Uma falha do Graphify não derruba o Memory Core.

Operational / Temporal Memory

O Work Graph no PostgreSQL registra entidades, relações e eventos cronológicos. Relações automáticas incluem:

Agent --EXECUTED--> Task --CREATED--> Decision
Task --FOUND--> Error --RESOLVED_BY--> Solution
Task --CHANGED--> File
Task --PRODUCED--> Commit
Task --FINISHED_AT--> Checkpoint

relations_query, trace_relationships e as tools de timeline respeitam o escopo selecionado. Trace detecta ciclos e aceita profundidade de 1 a 4.

Hybrid GraphRAG

context_retrieve pode combinar:

1. memória semântica;

2. filtros estruturados para tarefas, decisões e erros;

3. contexto estrutural do Graphify;

4. relações e timeline do Work Graph;

5. importância e recência.

A entrada permite orçamento de itens, memórias, tarefas, decisões, erros, nós e profundidade. A resposta deduplica entidades e informa fontes como MEMORY, TASK, DECISION, ERROR, CHECKPOINT, FILE e COMMIT.

Multi-Agent Handoff

Agentes são registrados com identidade independente do provedor. Uma sessão armazena estado e resumo, sem promover notas brutas automaticamente. agent_handoff reúne tarefas, decisões, erros, soluções, arquivos, commits e checkpoint relevantes para quem continua.

task_assign usa bloqueio transacional. Quando a tarefa já está em andamento por outro agente, o takeover exige force_takeover: true e fica registrado como relação operacional.

Observability e Dashboard

O dashboard em /dashboard é administrativo, autenticado, técnico e principalmente somente leitura. Ele mostra overview, projetos, repositórios, agentes, sessões, tarefas, memórias, decisões, erros, checkpoints, timeline, relações, métricas e auditoria. Ainda não é uma interface de produto final.

As operações MCP são auditadas com tool, escopo, status, duração e quantidade de itens. Argumentos, corpos de resultado, headers, tokens e exceções brutas não entram no audit log.

export_docs gera documentos Markdown derivados da memória. A fonte de verdade continua sendo o banco.

MCP tools

O servidor registra 35 tools. A lista categorizada e os nomes exatos estão em docs/MCP_CLIENTS.md.

Fluxo sugerido:

project_select
project_context
recall
session_start
start_task
record_decision / record_error / record_solution
git_snapshot
finish_task
checkpoint
session_finish
agent_handoff

Uso local

Pré-requisitos

• Docker Engine com Docker Compose;

• Git;

• Node.js 20 ou superior para execução no host;

• uma chave administrativa local para BRAIN_API_KEY.

Crie o ambiente local sem versionar segredos:

cp .env.example .env
# Edite .env e substitua todos os CHANGE_ME.
docker compose up -d --build
docker compose ps
curl http://127.0.0.1:3338/health

O MCP HTTP fica em http://127.0.0.1:3338/mcp. API, MCP e dashboard exigem BRAIN_API_KEY; o healthcheck é público e não expõe credenciais.

MCP stdio

Para clientes que executam o Jatobá localmente:

docker compose -f docker-compose.yml -f docker-compose.local.yml up -d postgres
npm install
npm run build
npm run mcp:stdio

Use config/local-stdio-mcp.json.example e configure DATABASE_URL localmente. Exemplos para Claude e Codex estão em config/claude-mcp.json.example e config/codex-config.toml.example.

Validação local

A implementação foi validada localmente com PostgreSQL, pgvector, Graphify, Docker e os transportes MCP reais.

• 27 cenários integration/release passando;

• build TypeScript e typecheck aprovados;

• Compose, build Docker e runtime aprovados;

• persistência confirmada após restart;

• Graphify real, isolamento de projeto/repositório, Work Graph, Hybrid GraphRAG, handoff, dashboard autenticado e observabilidade exercitados.

A qualidade semântica foi validada estruturalmente com embeddings determinísticos de teste. Uma avaliação de relevância com modelo de embeddings real ainda está pendente.

Execute a validação:

npm run build
npm run typecheck
# Os cenários estruturais exigem Graphify CLI 0.9.55 acessível em GRAPHIFY_BIN.
GRAPHIFY_BIN=graphify npm test
npm run test:release
docker compose config

Roadmap

v0.1 — Persistent Memory

• PostgreSQL

• pgvector

• MCP

• Projects

• Repositories

• Tasks

• Decisions

• Errors/Solutions

• Checkpoints

• Text fallback

v0.2 — Structural Memory

• Graphify integration

• Repository knowledge graph

• READY/STALE graph state

• Dependency/impact queries

v0.3 — Temporal Work Graph

• Agent → Task

• Task → Decision

• Task → File

• Error → Solution

• Commit/Checkpoint relationships

• Project timeline

v0.4 — Hybrid GraphRAG

• Semantic + graph retrieval

• Hybrid ranking

• Context budgeting

• Traceability

• Fallbacks

v0.5 — Multi-Agent Handoff

• Sessions

• Agent handoff

• Task ownership

• Explicit takeover

• Cross-agent continuation

v0.6 — Observability

• Metrics

• Audit logs

• Dashboard

• Timeline visualization

• Automatic document export

Current limitations

• A qualidade semântica ainda precisa ser avaliada com um modelo de embeddings real.

• A autenticação usa uma chave administrativa compartilhada.

• Algumas métricas representam estado atual, não counters históricos imutáveis.

• Graphify ainda precisa de política de retenção para snapshots antigos.

• Upgrade de PostgreSQL existente exige backup e análise prévia.

• Testes de carga ainda não foram realizados.

• Operação prolongada de produção não foi validada.

• HTTPS ainda não foi configurado.

Segurança

Nunca versione .env, chaves, tokens, backups, node_modules, dist ou dados de volumes. O .gitignore cobre esses caminhos e .env.example contém somente placeholders.

Antes de expor o serviço, use uma chave longa, restrinja ALLOWED_HOSTS, configure HTTPS e valide backup/restauração do PostgreSQL.

Licença

MIT. Consulte LICENSE.