reflect

reflect

Long-term memory for AI coding agents — correct once, never again.

reflect captures every correction and design decision your AI assistant makes, indexes them into a hybrid GraphRAG + BM25 knowledge base, and auto-recalls the relevant ones at the start of every new session — automatically, before the first token of your prompt is generated.

Works across Claude Code, Codex CLI, and GitHub Copilot — same engine, same KB, three harnesses.

📖 Full documentation → stevengonsalvez.github.io/agents-in-a-box — architecture, per-harness setup, and the Postgres backend in depth.

---

Why

If you've used AI coding assistants for more than a week, you've corrected the same mistake twice. Maybe ten times. The assistant doesn't remember that:

• Your team uses Bun, not Node, for that one repo
• The Postgres migration in your project must run before the seed
• That third-party library has a footgun you discovered last month
• "When I ask you to delete files, also clean the imports"

The context window forgets the moment the session ends. reflect fixes that by capturing corrections as structured learnings, indexing them into a searchable knowledge base, and recalling the relevant ones at the start of every new session — so a fix you make once is a fix you never have to make again.

---

Install

The engine lives at the repo root — install it with uv and the [graph] extra (pulls the full GraphRAG + vector stack):

uv tool install --upgrade 'git+https://github.com/stevengonsalvez/ainb-reflect-memory.git[graph]'

Verify with reflect --version.

Quickstart

reflect init                                    # one-time: create the KB at ~/.claude/global-learnings/
reflect add ./my-solution.md                    # capture a learning (optional --entities sidecar)
reflect search "how did we fix the tokio panic" # hybrid GraphRAG + BM25 recall

Plugin (Claude Code)

The plugin (hooks + skills) that wires reflect into your agent harness lives under plugin/. Install it from this repo's marketplace:

claude plugin marketplace add stevengonsalvez/ainb-reflect-memory
claude plugin install reflect@ainb-reflect-memory

See plugin/README.md for the lifecycle hooks, sub-skills, and the Codex / Copilot adapters. (ainb reflect bootstrap installs the engine + prints system-tool steps in one shot.)

---

How it works

reflect runs a capture → index → recall loop:

1. Capture — /reflect analyses your conversation, classifies corrections vs. successes, and writes a Markdown learning note plus a YAML entity sidecar (people, files, libraries, decisions). A PreCompact hook fires automatically when the agent compacts a conversation, so nothing is lost.
2. Index — notes are dual-indexed: nano-graphrag for semantic + entity-graph search, qmd for fast BM25 lexical search. Both run locally on your machine — nothing leaves it.
3. Recall — at every SessionStart, a hook runs hybrid search using the new session's working dir + recent commits as the query, fuses the results, reranks by confidence × recency × tag overlap, and injects the top three into the agent's context before you type anything.

---

Two ways to run: local or shared

The markdown KB (~/.claude/global-learnings/*.md) is always the local source of truth, and all LLM/embedding/clustering always stays client-side. What changes between the two modes is only the derived vector + graph store.