convez.ai
AgenteAutomaçãoIntermediário
krish-shahh

Agent Findings

krish-shahh/agent-findings

Memória compartilhada para agentes de código reterem e reutilizarem conhecimento

Ver no GitHub
BomPluginScore · de 0 a 100

Camada de aprendizado coletivo entre sessões para agentes Claude Code e Codex. Permite que agentes reutilizem descobertas de execuções anteriores através de um repositório compartilhado, evitando reaprendizado de problemas já resolvidos.

Instalação

$npx convez-ai krish-shahh/agent-findings

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
2
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Acelerar resolução de problemas recorrentes em debugging
  • Compartilhar padrões de solução entre múltiplas sessões de agentes
  • Construir base de conhecimento incremental para tarefas de codificação

Veredito

Solução criativa que resolve um problema real — agentes perdendo conhecimento entre sessões. Implementação shell-native é leve e prática, mas requer adoção de fluxo de distilação manual (/distill) que pode friccionar usabilidade em workflows automáticos puros.

README

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

agent-findings

A cross-session collective-learning layer for Claude Code and Codex agents.

Every agent starts with amnesia. It solves something, the session ends, and the lesson evaporates. The next agent relearns it from scratch.

agent-findings fixes that: after every task an agent writes down what it learned, before every task it reads back what past runs figured out. Both Claude Code and Codex write to and read from the same store.

Blog post: i gave my coding agents a shared memory


Install

Requires jq. On macOS: brew install jq. Distillation uses the agent CLI you already have installed — Claude Code (claude) or Codex. No separate API key needed.

Claude Code

curl -fsSL https://raw.githubusercontent.com/krish-shahh/agent-findings/main/install.sh | bash

The installer will ask whether to enable distillation (recommended — say yes). Restart any running Claude Code sessions and you're done.

Codex (standalone — does not require the Claude Code install)

git clone https://github.com/krish-shahh/agent-findings.git
cd agent-findings && ./install-codex.sh

Restart Codex and approve the three new hooks when prompted. Both agents share the same ~/.agent-findings store.

Both installers are independent. Run either one, or both — they write hooks to the same neutral location (~/.agent-findings/hooks/) so there's no conflict.

git clone https://github.com/krish-shahh/agent-findings.git
cd agent-findings
./install.sh          # Claude Code (standalone)
./install-codex.sh    # Codex (standalone)

To uninstall (findings are kept): ./uninstall.sh


How it works

sequenceDiagram
    participant P as user prompt
    participant R as findings-reader.sh
    participant S as ~/.agent-findings
    participant C as agent (claude/codex)
    participant D as /distill skill

    P->>R: UserPromptSubmit hook
    R->>S: score index by tags + task_type
    S-->>R: top 3 findings
    R-->>C: inject prior knowledge block
    P-->>C: original prompt
    Note over C: executes task
    Note over C: user types /exit
    C->>C: exit guard fires (UserPromptSubmit)
    C->>D: blocked — run /distill first
    D->>S: write {uuid}.json · reindex
    Note over C: user types /exit again → exits
  • findings-reader.sh — before every prompt, scores the store by keyword overlap against task_type and tags, injects the top 3 as a prior-knowledge block. Pure shell + jq, nothing slow.
  • findings-exit-guard.sh — intercepts /exit and /quit when AGENT_FINDINGS_ENABLED=1. Blocks until the session is distilled, then lets the exit through.
  • /distill skill — Claude extracts a finding from the current session in-session (no extra model call, uses your active subscription), writes it to the store, and unblocks exit.

The finding

One JSON file. One reusable lesson. The schema is the protocol — anything that writes this shape interoperates.

{
  "schema_version": "1.0",
  "id": "7c2a1e90-4b3d-4f1a-9c2e-0a1b2c3d4e5f",
  "task_type": "debugging",          // kebab-case — the retrieval key
  "language": "python",
  "what_worked": "the flaky test was a clock dependency. injecting a clock made it deterministic.",
  "what_failed": "spent 20 min adding retries assuming a network race — re-running 'until green' hid the non-determinism.",
  "better_exit_condition": "a test that passes on retry but fails in isolation means non-determinism in the code, not the harness.",
  "tags": ["flaky-test", "pytest", "non-determinism"],
  "confidence": 0.86,                // below 0.5 is never stored
  "timestamp": "2026-06-08T22:00:00Z",
  "source": { "agent": "claude-code", "session_id": "…", "cwd": "…" }
}

Full schema: schema/finding.schema.json · Example: examples/

Protocol rules: one finding per file, immutable, append-only, confidence-gated. index.json and stats.json are caches — agent-findings reindex rebuilds them from the files at any time. Because findings are UUID-addressed and immutable, merging two stores is a set union — no conflicts, ever.


Store layout

~/.agent-findings/
├── index.json              # tag index + finding summaries (cache)
├── hooks/                  # agent-neutral hook scripts (shared by Claude Code + Codex)
│   ├── findings-writer.sh
│   ├── findings-reader.sh
│   ├── findings-session-init.sh
│   └── findings-exit-guard.sh
├── findings/
│   └── {task_type}/
│       └── {uuid}.json     # source of truth
└── meta/
    ├── stats.json
    ├── writer.log
    ├── current-session     # session_id of the active session (written by SessionStart hook)
    └── distilled-{sid}     # sentinel: this session was distilled (unblocks /exit)

CLI

agent-findings list [N]        # recent findings (default 10)
agent-findings show <id>       # full finding by id or prefix
agent-findings search <query>  # find by keyword
agent-findings delete <id>     # remove a finding
agent-findings stats           # totals, top task types, top tags
agent-findings reindex         # rebuild index from files
agent-findings sync            # push/pull with a shared remote (stub)

Sync

The data model is built for sharing. Findings are immutable and UUID-addressed, so merging two stores is a set union of {uuid}.json files — no conflicts.

agent-findings sync is a documented stub. You can DIY today:

git -C ~/.agent-findings init
git -C ~/.agent-findings add findings
git -C ~/.agent-findings commit -m "findings"
git -C ~/.agent-findings remote add origin <url> && git -C ~/.agent-findings push -u origin main

Planned: agent-findings sync push/pull against a shared git remote.


Distillation (opt-in)

Distillation is the step where findings actually get written — Claude reads what happened in the session and extracts a structured lesson. It runs entirely in-session via the /distill skill, so it uses your active subscription and costs nothing extra.

Distillation is off by default. Set AGENT_FINDINGS_ENABLED=1 to enable the exit guard, which prompts you to distill before each /exit.

echo 'export AGENT_FINDINGS_ENABLED=1' >> ~/.zshrc  # or ~/.bashrc

The exit flow when enabled:

user:  /exit
guard: agent-findings: session not yet distilled.
       Run /distill to save what you learned, then /exit again.

user:  /distill
claude: [reads session context, structures finding, writes JSON, rebuilds index]
claude: "Finding saved (api-integration · 0.82). You can now /exit."

user:  /exit   ← guard sees sentinel, exits cleanly

To skip distillation for a session: set AGENT_FINDINGS_ENABLED=0 temporarily, or just type /exit twice (the guard message tells you how).

The findings-writer.sh Stop hook is also present but is a no-op unless AGENT_FINDINGS_ENABLED=1 — it exists for Codex compatibility where the /distill skill isn't available. For Codex users, the Stop hook calls claude -p for distillation; starting June 15 2026, claude -p draws from Agent SDK credits rather than your subscription, so Codex distillation has a small per-session cost.


Configuration

VariableDefaultEffect
AGENT_FINDINGS_ENABLEDunsetSet to 1 to enable distillation (opt-in, see above)
AGENT_FINDINGS_HOME~/.agent-findingsStore location
AGENT_FINDINGS_TOP_N3Findings injected per prompt
AGENT_FINDINGS_MAX500Hard cap on stored findings; oldest+weakest pruned on write
AGENT_FINDINGS_HALF_LIFE_DAYS90Age-decay half-life in days (used for scoring and pruning)
AGENT_FINDINGS_TRANSCRIPT_BYTES60000Transcript cap for distiller
CODEX_CLI/Applications/Codex.app/…/codexOverride Codex CLI path

Contributing

A finding is just a JSON file. Write the same shape from Cursor, Aider, Codex, a CI job, or your own agent and it drops straight into any store. See CONTRIBUTING.md.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados