robo-cortex

Git-aware knowledge integrity for AI coding agents.

Your AI agent debugs a bug, learns the lesson, and forgets it by next week — or worse, keeps citing a "lesson" that the code has since made false. robo-cortex is a local knowledge base built for that specific failure mode: memories are anchored to git blob hashes, so when the code they're about changes, the memory is automatically flagged for review instead of being silently trusted or silently lost. In other words: drift detection and stale-memory detection for AI agent memory, done deterministically from git history — not an LLM guess, not an embedding-similarity heuristic.

Why robo-cortex, not another memory tool

Most agent-memory tools are embeddings + a vector database + a cloud dependency. robo-cortex is deliberately none of that. Four things it does that a generic key-value memory store doesn't:

1. Git-aware staleness (drift) detection. Every memory can link to specific file paths, captured by git blob hash at record time. When the linked code changes, the memory is automatically flagged needs_review on the next retrieve/search/affected call — and a committed revert automatically heals it back. The healing requires three conditions: (a) the revert must be committed (git blob hash must match HEAD again), (b) the memory must have been flagged by the system (not manually via change_status), and (c) you must run a lazy trigger (retrieve/search/affected) after the revert to scan for changes. Few memory tools tie themselves to your actual code's history this deterministically — no embedding similarity, no LLM judgment call, just a git blob hash matching or not.
2. Evidence, not vibes. Memories can carry attached evidence (test output, a commit, a re-runnable command) with a mechanically computed strength — not a judgment call. A provisional memory only becomes active once real evidence backs it, or a human explicitly promotes it.
3. Zero dependencies, fully local. Pure stdlib + SQLite (FTS5 for search). No embeddings, no API keys, no network calls unless you explicitly configure Gitea evidence verification. .cortex/memory.db is just a file — inspect it with sqlite3 any time.
4. A real lifecycle with an audit trail. Every status change (active → superseded → archived, etc.) requires a --reason, permanently recorded. Nothing disappears silently; wrong lessons are marked invalidated, not deleted.

Measured impact (benchmark, honestly stated)

A 30-session benchmark (3 real historical bugs from this repo, re-introduced and solved 10× each by a small model — Claude Haiku 4.5 — with and without a robo-cortex memory pack) measured, at identical fix quality (30/30 correct, zero disqualifications): ~12% fewer fresh tokens and ~15% lower API-equivalent cost (medians of paired per-task deltas), scaling up to −26% tokens / −39% cost on the task whose fix was hardest to locate unaided. Recording a lesson was itself metered: a memory pays for itself after ~1–6 sessions that reuse it (median ≈ 5). We make no wall-clock claim — time differences were noise-dominated. Full methodology, per-run raw evidence (usage logs, diffs, prompts), and the reusable harness are in the repo: docs/benchmark-results.md, benchmark-results-20260718/, scripts/benchmark/. Known limits, stated plainly: one subject model (small — an earlier n=3 pilot on a larger model measured a smaller 2.7% effect, see EVALUATION.md §9), one well-documented codebase (likely compresses the effect), 3 task types. We'd rather publish a modest number we measured than a dramatic one we didn't.

Quick Start

Prerequisite: robo-cortex requires a git repository (staleness detection needs git history to compare against):

git init && git add -A && git commit -m "initial commit"

Installation

pip install robo-cortex

If pip install refuses with error: externally-managed-environment (common on recent Debian/Ubuntu), use a virtual environment or pipx:

python3 -m venv .venv && source .venv/bin/activate && pip install robo-cortex
# or: pipx install robo-cortex

If you plan to use robo-cortex with an MCP-capable agent (Claude Desktop/Code, etc.), install the MCP extra instead:

pip install 'robo-cortex[mcp]'

Usage

cd /path/to/your/project
roco init

# Record a project-specific lesson (scope=repo: no extra fields needed)
roco record --type lesson --scope repo \
  --statement "Copy-to-clipboard fails on HTTP; use a textarea+execCommand fallback." \
  --confidence high

# Retrieve it later
roco retrieve --task "copy to clipboard http"

matched=1 returned=1 needs_review=0 contradicted=0
[1] score=0.650 repo   lesson       Copy-to-clipboard fails on HTTP; use a textarea+execCommand fallback.

--path links a memory to a file, but only accepts a path that already exists at HEAD (no memory is ever born pointing at a dead link). For code you just wrote but haven't committed yet: record the memory without --path now, commit, then attach the path afterward:

roco record --type decision --scope repo --statement "..." --confidence high
# id=7, no linked path yet

git add new_module.py && git commit -m "add new_module.py"
roco record 7 --add-path new_module.py

Reusable lessons (not specific to this project) use scope=global and require --assumptions — the conditions under which the lesson applies, so it doesn't get suggested everywhere by accident:

roco record --type lesson --scope global \
  --statement "Safari 14 breaks CSS grid+gap. Use flexbox+margin instead." \
  --confidence high \
  --assumptions "css grid gap safari"

Global-scope commands (record --scope global, show, search, status, link, evidence, list) work from anywhere, including outside any git repository — the global store (~/.cortex/global.db) isn't tied to a project. retrieve is the one exception: it's local-repo-aware by design, so it still requires an initialized repo.

Enable enforcement (recommended)

roco hooks install

Installs a git pre-commit hook: if the commit touches code linked to a memory that's active/provisional/needs_review, the commit is blocked with the memory's id and a review prompt, until you've reviewed it or bypassed explicitly. Example, for a memory linked to src/scanner.py when that file is part of the commit:

robo-cortex: this commit touches code linked to memories that need review:
  [1] path_changed:src/scanner.py@working_tree  scanner batches at 50 items deliberately

Review with: roco show <id>
Then either re-verify (roco status <id> activate --reason "...") or supersede it, and commit again.
To bypass this check: git commit --no-verify

The bypass is real and documented — git commit --no-verify skips it, same as any git hook. This is "enforcement by default, bypass explicit," not "impossible to skip." See roco hooks --help for uninstall/status. For a CI-level check on pull requests instead of (or in addition to) local commits, see docs/ci-example.yml.

There's also an optional post-commit hook, purely informational (it never blocks — the commit it reports on already happened by the time it runs):

roco hooks install --post-commit

It runs roco affected --diff-range HEAD~1..HEAD after each commit and reports anything at risk, so a flag shows up immediately instead of waiting for the next retrieve/search/affected call. --post-commit also works with uninstall/status, independently of the pre-commit hook.

Shorthand: roco

Both robo-cortex and roco are identical commands (same binary, two script entry points). Use whichever fits your fingers:

roco retrieve --task "..."          # Shorter alias
robo-cortex retrieve --task "..."   # Full name, backwards compatible

Name collision note: PyPI already has an unrelated package named roco ("Runtime Config Generator"). If that package is also installed in the same environment, whichever was installed last wins the roco command — use the full robo-cortex name to be unambiguous, or check roco --version to confirm which one you're actually running.

Shell completion

roco completion bash >> ~/.bashrc

Completes subcommand names and each subcommand's own flags (not flag values, and not nested sub-subcommands like hooks install). It's a static script generated from the installed version — re-run the command after upgrading to pick up new commands or flags.

Three ways to use it