robo-cortex is a Git-aware, evidence-driven memory storage tool for AI coding agents, developed and open-sourced by Robotel Limited UK. The core problem it addresses is: after a coding agent reaches a conclusion through debugging, it tends to forget, or continues to cite old "lessons" that have already been overturned by code changes. robo-cortex anchors memories to Git blob hashes, and when the associated code changes, it automatically marks the memory as pending review, rather than being silently trusted or silently lost, that is, it performs deterministic drift detection and staleness detection on agent memory, based on Git history rather than LLM judgment or embedding similarity.
Purpose To provide AI coding agents with a trustworthy local knowledge base, so that debugging experience, project decisions, and reusable lessons can be recorded, retrieved, and verified, while promptly exposing memories that may have become invalid after code evolution.
Main capabilities Git-aware staleness (drift) detection: each memory can be associated with a specific file path, and the Git blob hash is captured when it is recorded. When the associated code changes, the next retrieve, search, or affected call will automatically mark it as needs_review; a committed rollback can automatically restore it, and restoration must satisfy three conditions: (a) the rollback has been committed (the Git blob hash matches HEAD again), (b) the memory was marked by the system rather than by a manual change_status, and (c) after the rollback, a lazy trigger (retrieve, search, or affected) was run to scan for changes. Evidence rather than "feeling": memories can carry evidence (test output, commits, repeatable commands), and strength is calculated mechanically. Tentative memories only become active after they receive real evidence support or an explicit manual upgrade. Zero dependencies, fully local: pure standard library plus SQLite (search uses FTS5). No embeddings, no API keys, no network calls, unless Gitea evidence verification is explicitly configured. .cortex/memory.db is just a file and can be inspected at any time with sqlite3. A real lifecycle with an audit trail: every status change (active → superseded → archived, etc.) requires a --reason and is permanently recorded; erroneous lessons are marked as invalidated rather than deleted.
How to use Prerequisites: a Git repository is required (staleness detection needs Git history for comparison).If pip install fails with an externally-managed-environment error (common on newer Debian/Ubuntu), use a virtual environment or pipx. To use it with MCP-capable agents (Claude Desktop/Code, etc.), install the MCP extra. --path is used to link a memory to a file, but it only accepts paths that already exist at HEAD (it will not create memories pointing to dead links); for code that has just been written but not yet committed, you can first record the memory without --path, then attach the path after committing. For reusable lessons (not project-specific), use scope=global, and you must provide --assumptions to explain the conditions under which the lesson applies. Global-scope commands (record --scope global, show, search, status, link, evidence, list) can be run from anywhere, including outside a Git repository, because the global store ~/.cortex/global.db is not bound to a project; retrieve is the exception, as it is local-repository-aware by design and still requires an initialized repository. Three ways to use it: CLI, MCP, and Python SDK, all three calling the same robo_cortex.core functions. The CLI provides two equivalent command names, robo-cortex and roco (the same binary, two script entry points). Note that there is already an unrelated package with the same name, roco (Runtime Config Generator), on PyPI; if installed in the same environment, whichever is installed later will occupy the roco command, in which case you should use the full robo-cortex name or confirm with roco --version. Available MCP tools include retrieve_context, record_memory, search_memory, attach_evidence, verify_evidence, change_status, get_memory, and list_affected; see MCP_TOOLS.md for the full contract; see PYTHON_SDK.md for the Python SDK. There is also Shell completion (completing subcommand names and each subcommand's own flags, but not flag values, nor nested subcommands such as hooks installcommands), which is a static script generated based on the installed version, and must be rerun after upgrading. Enforced constraints (optional, recommended): after installing the Git pre-commit hook, if a commit touches code associated with memories in active, provisional, or needs_review status, the commit will be blocked and the memory id and a review prompt will be given, until review or explicit bypass; the bypass method is git commit --no-verify, which is "enforced by default, explicitly bypassable." An optional post-commit hook is also provided, purely notification, does not block commits, and runs roco affected --diff-range HEAD~1..HEAD after each commit and reports risky content. For CI-level checks, see docs/ci-example.yml. Status lifecycle: new memories start as provisional; after attaching evidence via roco evidence add, they automatically change from provisional to active; you can manually change status with roco status <id> <verb> --reason "...", where --reason is mandatory and permanently recorded and cannot be edited. Knowledge sharing: export/import supports cross-project sharing, import is idempotent (skips duplicates by id+scope) and validates like record; scope=global entries missing assumptions or with illegal type/confidence will be skipped with a warning. roco merge can merge two independently learned projects, deduplicating by ID+scope, with conflicts resolved in favor of the higher confidence, and timestamps as the tiebreaker. Official warning: do not point ROBO_CORTEX_GLOBAL_DB at a network file system (NFS/SMB) to "share team memory"; SQLite concurrent writes on network mounts are unsafe and may corrupt the database; share via Git export/import instead.
Use cases Suitable for teams and individuals doing long-term project development with AI programming agents, for recording in-project conventions and decisions (scope=repo, such as choosing FastAPI + SQLAlchemy, batch sizes adjusted for their own infrastructure) as well as reusable lessons (scope=global, such as browser/library defects, language/framework patterns, SQL injection protection and other best practices), and automatically discovers invalidated memories through Git history, preventing agents from referencing outdated experience.
Limitations and known circumstances A Git repository is required to use Git-aware features such as stale detection, path linking, and affected; without Git, export/import/merge can still be used to migrate knowledge between machines. Official benchmark: 30 sessions (3 real historical defects, each reproduced and resolved 10 times by the small model Claude Haiku 4.5 with and without the robo-cortex memory pack), under equal fix quality (30/30 correct, zero dropouts), median reduction of about 12% in fresh tokens and about 15% in API-equivalent cost, and on the hardest-to-locate defect tasks without assistance, up to 26% token reduction / 39% cost reduction; recording a lesson itself is also counted in the measurement, and memory pays for itself after about 1 to 6 reuse sessions (median about 5); no wall-clock time claims are made. Known limitations: a single subject model (smaller; an earlier n=3 pilot against a larger model measured a smaller 2.7% effect, see EVALUATION.md §9), a single well-documented codebase (possible compression effect), 3 task types. The enforcement hook can be bypassed with git commit --no-verify. With a read-only database, retrieve/search/affected degrade gracefully, read returns results, writes (stale refresh, usage tracking) are skipped, and a warning is given in meta. Global storage can be fully opted out via ROBO_CORTEX_NO_GLOBAL=1. Designed and tested at a scale of thousands of memories per store, with performance degrading gracefully beyond that, scoring is O(n) over candidates, and the FTS candidate set per store is capped at 200. Performance timing differences were dominated by noise in testing. No embeddings, no cloud. MIT licensed, open source, no telemetry, no vendor lock-in, free to use.
