convez.ai
AgenteDevOps & InfraestruturaAvançado
EvolutionUnleashed

BIMRI - Infraestrutura de Memória para Agentes de Código

EvolutionUnleashed/bimri-claude-code

Memória persistente e recuperável para agentes de código com continuidade entre sessões

Ver no GitHub
InicialPluginScore · de 0 a 100

BIMRI é uma infraestrutura de memória em camadas para agentes de IA que trabalham com código. Mantém um arquivo de memória ativo e limitado em tamanho, armazenando detalhes completos em disco com recuperação via grep, e permite que agentes construam continuidade e padrões que se acumulam ao longo do tempo através de journaling write-ahead.

Instalação

$npx convez-ai EvolutionUnleashed/bimri-claude-code

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
8
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 meses
Versão
v1.2.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Agentes Claude Code que precisam manter contexto entre sessões de trabalho
  • Automação com agentes que rodam em schedules ou crons sem supervisão humana
  • Sistemas que precisam recuperar de falhas mid-flight sem perder informações críticas
  • Projetos de longa duração onde padrões e decisões passadas devem informar o trabalho futuro

Veredito

Solução sofisticada e bem pensada para um problema real em agentes de IA: como manter memória eficiente que cresce sem explodir tokens. A implementação via write-ahead logs e compactação automática é sólida, mas requer entendimento técnico profundo e integração cuidadosa. Recomendado para quem constrói sistemas de agentes que rodam continuamente ou em múltiplas sessões.

README

A tradução para o português deste README ainda está na fila.

BIMRI: Memory Infrastructure For Coding Agents

Brief Interaction Memory And Retrieval Intelligence - v4

BIMRI gives coding agents memory that compounds. It keeps a small, permanently bounded memory file in context, stores full detail on disk behind pointers, and grows more valuable over time through evidence-backed pattern recognition.

The core rules:

bimri.md is not a diary. It is the current operating state.

Write ahead. Journal at the moment of decision, never reconstruct at the end.

Headlines live in hot memory. Bodies live on disk, one grep away.

Two Modes, One Infrastructure

BIMRI is one core product that runs in two modes. Both modes share the same engine, the same protocol, the same memory format, and the same files. The difference is who supervises the run.

BIMRI Session is for interactive work. You open a project, the agent orients from memory of every past session, you work, and the record updates so the next session inherits everything. Continuity is the product: cold-start orientation, durable decisions, and patterns that compound across weeks.

BIMRI Loop is for scheduled agents. It is Session plus the unattended-operation layer: orphan recovery for runs that die mid-flight, outcome telemetry that turns failure modes into percentages, and cap enforcement that holds while nobody watches.

Choosing takes one question. A human is in the chair: Session. The agent runs on a cron or schedule: Loop. Switching later is one config field, so nothing about the choice is permanent.

Quick Start: BIMRI Session

  1. Copy all nine BIMRI files into your project root.
  2. For Claude Code, merge hooks-example.json into .claude/settings.json and verify with /hooks. The engine now briefs the agent automatically at session start and closes the run at session end. Without hooks, AGENTS.md instructs the agent to run python3 bimri-engine.py start as its first action, so it works either way.
  3. Start a session and work normally.

Session write timing: the agent gets its brief at start and writes durable memory before the session closes. Short sessions may write their full detail once at the end. Sessions that run long escalate to journaling at milestones, because auto-compaction summarizes detail away mid-session and an end-of-session write can only record what survived. Journaling ahead of compaction is what preserves fidelity.

Minimal install: if you want zero scripts, copy only AGENTS.md, CLAUDE.md, BIMRI-PROTOCOL.md, and the two templates. The agent handles its own bookkeeping using the fallback rules in the protocol. Functional, lighter, less reliable, and Session-only.

Quick Start: BIMRI Loop

  1. Copy all nine BIMRI files into your project root. The engine is required in Loop mode, since deterministic maintenance with nobody watching is the whole point.
  2. Open .bimri/state.json after the first run and set cadence_class to daily_cron or hourly_cron. This selects a decay curve scaled to your run frequency.
  3. Wire the cron entry. The semicolon matters: closure must run even when the agent dies.
cd /path/to/project && python3 bimri-engine.py start && <agent command> ; python3 bimri-engine.py close

Loop write timing: journal every decision the moment it happens, no exceptions. Unattended runs die without warning, and write-ahead journaling is why a run that overflows at the turn limit still loses nothing. The next start detects the orphaned run, recovers anything durable, and stamps it closed with an [OUTCOME:overflow] line. Run python3 bimri-engine.py status anytime to see outcome statistics across all runs, including your overflow rate.

What Changed In v4

Every prior version had one root cause of drift: the model was its own maintenance engine. Run counting, decay math, budget checks, and archival all landed on the model at the end of a session, when context is fullest and attention is thinnest. Models are unreliable at deterministic bookkeeping, so pruning fired sometimes and memory bloated the rest of the time.

v4 splits the work. Arithmetic moves into bimri-engine.py, a single dependency-free Python script. Judgment stays with the agent. Specifically:

  • Hot memory becomes headlines and pointers. Every entry in bimri.md is one line pointing at its full record in .bimri/log/. The file stabilizes around 1 to 1.5k tokens permanently.
  • Caps replace token budgets. Tier 1 holds 12 lines, Tier 2 holds 20, Tier 3 holds 8 patterns. Line counts are enforceable by a script and by a model; token estimates are enforceable by neither.
  • Run logs are append-only and write-ahead. Decisions are journaled as they happen in 30-token appends, so a dying run still leaves a complete record.
  • The index makes pruning safe. .bimri/index.tsv maps every ID to its location, so archived memory stays one grep away. Agents stop hoarding context once nothing is ever truly lost.
  • Decay is cadence-aware. Session work and hourly loops select different freshness curves through one config field.
  • Outcomes become data. Every run log closes with an [OUTCOME:] line the engine aggregates across runs.
  • Patterns graduate. Established patterns with surviving evidence promote into Tier 1 as operating rules. Observation becomes pattern becomes rule becomes changed behavior.

How Memory Flows

  1. Start. The engine counts the run, archives the unambiguous (closed entries, fully decayed minor ones), flags decayed entries for judgment, detects orphaned runs, opens this run's log, and prints a brief.
  2. Work. The agent journals [ID:] entries into the run log and refreshes [L:] on hot entries that recur.
  3. Close. The agent writes an [OUTCOME:] line and durable headlines, then the engine stamps closure, enforces caps, and rebuilds the index.
  4. Compound. Evidence accumulates, patterns strengthen, established patterns graduate into Tier 1 rules that change behavior in every future session.

The Files

FilePurpose
AGENTS.mdCross-agent bootstrap, the first file many agents read.
CLAUDE.mdClaude Code bridge that imports AGENTS.md.
BIMRI-PROTOCOL.mdFull protocol: formats, decay tables, lifecycle, recovery.
bimri-engine.pyDeterministic engine. Stdlib only, no dependencies. Optional in Session, required in Loop.
hooks-example.jsonClaude Code hook wiring for automatic start and close.
BIMRI-MEMORY.template.mdTemplate for bimri.md hot memory.
BIMRI-STATE.template.jsonTemplate for .bimri/state.json.
MIGRATION.mdGuided path from v3.
bimri.mdCreated in each project. Hot memory, headlines and pointers only.

Token Math

An hourly Loop agent under v3 read a 3 to 4k token memory file at start, read it again before updating, then rewrote the whole thing: roughly 10k tokens of memory overhead per run, 240k per day, with corruption risk on every rewrite. Under v4 the same agent reads a 1.5k hot file and appends under 200 tokens: roughly 2k per run, under 50k per day. Better recall at a fifth of the cost, and the rewrite step that corrupted files is gone entirely.

Manual Commands

python3 bimri-engine.py status     # sizes, caps, run outcome statistics
python3 bimri-engine.py maintain   # force a safe archival pass plus judgment brief
python3 bimri-engine.py index      # rebuild the index from all memory files

The engine never hard-deletes memory in any mode. Archival moves lines to .bimri/archive/ with provenance stamps, and hot memory is backed up before every modification.

Privacy

For teams, decide whether memory ships in git. If it may contain private context:

bimri.md
.bimri/

Migrating From v3

See MIGRATION.md for the guided one-session path. IDs and pattern evidence carry over intact. Migration lands you in Session mode by default; Loop users then set cadence_class per the quick start above.

Author

Stu Jordan - Agent Orchestrator evolutionunleashed.com

License

MIT - see LICENSE for details.

Ver o original no GitHub

Bom para

Relacionados