robotel-limited/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):
Installation
If pip install refuses with error: externally-managed-environment (common on recent Debian/Ubuntu), use a virtual environment or pipx:
If you plan to use robo-cortex with an MCP-capable agent (Claude Desktop/Code, etc.), install the MCP extra instead: