robo-cortex 0.4.0__tar.gz → 0.4.2__tar.gz

{robo_cortex-0.4.0 → robo_cortex-0.4.2}/.gitignore

@@ -14,3 +14,4 @@ htmlcov/
 .cortex/
 .claude/
 .commandcode/
+bench-work/

{robo_cortex-0.4.0 → robo_cortex-0.4.2}/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project are documented here. Format loosely follows
 
 ## [Unreleased]
 
+## [0.4.2] — 2026-07-26
+
+### Changed
+
+- **`list_affected` MCP tool documentation.** Gave the tool a full `description=` (matching the other high-value tools) and per-parameter `Field` descriptions for `diff_range`/`staged`/`working`. The description now states concretely what the tool returns, excludes terminal-status memories, and — most importantly — spells out *when* to reach for it versus `retrieve_context` and `search_memory` (it is diff-driven, mapping a code delta to the memories that depend on it, not a task- or keyword-driven read). Documentation only; no behavior change. Raises the tool's Glama quality-score dimensions (behavior, completeness, parameters, purpose, usage guidelines).
+
+## [0.4.1] — 2026-07-15
+
+Adds the `mcp-name` ownership-verification marker to the README, required to publish robo-cortex to the official MCP Registry (registry.modelcontextprotocol.io). No functional changes.
+
 ## [0.4.0] — 2026-07-15
 
 First public PyPI release. All changes below were already complete in the unpublished `0.3.1` local build — this version bump exists solely to mark the public debut, not to introduce new behavior.

{robo_cortex-0.4.0 → robo_cortex-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: robo-cortex
-Version: 0.4.0
+Version: 0.4.2
 Summary: Long-term memory system for LLM coding agents working inside a Git repository
 Project-URL: Homepage, https://robotel.top
 Project-URL: Repository, https://github.com/robotel-limited/robo-cortex
@@ -29,7 +29,17 @@ Description-Content-Type: text/markdown
 
 # robo-cortex
 
-**A git-aware, evidence-based memory store for AI coding agents.**
+<!-- mcp-name: io.github.robotel-limited/robo-cortex -->
+
+[![PyPI version](https://badge.fury.io/py/robo-cortex.svg)](https://pypi.org/project/robo-cortex/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/robo-cortex.svg)](https://pypi.org/project/robo-cortex/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Smithery Calls](https://smithery.ai/badge/robotel-top/robo-cortex)](https://smithery.ai/servers/robotel-top/robo-cortex)
+[![robo-cortex MCP server](https://glama.ai/mcp/servers/robotel-limited/robo-cortex/badges/score.svg)](https://glama.ai/mcp/servers/robotel-limited/robo-cortex)
+
+[![robo-cortex MCP server](https://glama.ai/mcp/servers/robotel-limited/robo-cortex/badges/card.svg)](https://glama.ai/mcp/servers/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.
 
@@ -44,9 +54,9 @@ Most agent-memory tools are embeddings + a vector database + a cloud dependency.
 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.
 
-## Pilot measurement (informative, not definitive)
+## Measured impact (benchmark, honestly stated)
 
-A small, real evaluation pilot (3 runs per arm, **one task only**) measured **2.7% fewer tokens and 10.6% less wall-clock time** with robo-cortex versus without, at equal fix quality. This is a real but modest signal from a limited sample — see [EVALUATION.md](https://github.com/robotel-limited/robo-cortex/blob/main/EVALUATION.md) §9 for full methodology and caveats. Key limitations: n=3/arm (too small to generalize), one task type (may not represent typical workloads), and token-accounting asymmetry (doesn't credit avoided re-debugging when a stale lesson is caught before being retried, which is the real value proposition). We'd rather publish a modest number we measured than a dramatic one we didn't. **Not a benchmark** — a proof of concept that robo-cortex doesn't hurt wall-clock time in a realistic scenario, and may help on tokens. Definitive performance claims await a larger study across more task types.
+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](https://github.com/robotel-limited/robo-cortex/blob/main/docs/benchmark-results.md), [benchmark-results-20260718/](https://github.com/robotel-limited/robo-cortex/tree/main/benchmark-results-20260718), [scripts/benchmark/](https://github.com/robotel-limited/robo-cortex/tree/main/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](https://github.com/robotel-limited/robo-cortex/blob/main/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.
 
 ---
 

{robo_cortex-0.4.0 → robo_cortex-0.4.2}/README.md

@@ -1,6 +1,16 @@
 # robo-cortex
 
-**A git-aware, evidence-based memory store for AI coding agents.**
+<!-- mcp-name: io.github.robotel-limited/robo-cortex -->
+
+[![PyPI version](https://badge.fury.io/py/robo-cortex.svg)](https://pypi.org/project/robo-cortex/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/robo-cortex.svg)](https://pypi.org/project/robo-cortex/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Smithery Calls](https://smithery.ai/badge/robotel-top/robo-cortex)](https://smithery.ai/servers/robotel-top/robo-cortex)
+[![robo-cortex MCP server](https://glama.ai/mcp/servers/robotel-limited/robo-cortex/badges/score.svg)](https://glama.ai/mcp/servers/robotel-limited/robo-cortex)
+
+[![robo-cortex MCP server](https://glama.ai/mcp/servers/robotel-limited/robo-cortex/badges/card.svg)](https://glama.ai/mcp/servers/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.
 
@@ -15,9 +25,9 @@ Most agent-memory tools are embeddings + a vector database + a cloud dependency.
 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.
 
-## Pilot measurement (informative, not definitive)
+## Measured impact (benchmark, honestly stated)
 
-A small, real evaluation pilot (3 runs per arm, **one task only**) measured **2.7% fewer tokens and 10.6% less wall-clock time** with robo-cortex versus without, at equal fix quality. This is a real but modest signal from a limited sample — see [EVALUATION.md](https://github.com/robotel-limited/robo-cortex/blob/main/EVALUATION.md) §9 for full methodology and caveats. Key limitations: n=3/arm (too small to generalize), one task type (may not represent typical workloads), and token-accounting asymmetry (doesn't credit avoided re-debugging when a stale lesson is caught before being retried, which is the real value proposition). We'd rather publish a modest number we measured than a dramatic one we didn't. **Not a benchmark** — a proof of concept that robo-cortex doesn't hurt wall-clock time in a realistic scenario, and may help on tokens. Definitive performance claims await a larger study across more task types.
+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](https://github.com/robotel-limited/robo-cortex/blob/main/docs/benchmark-results.md), [benchmark-results-20260718/](https://github.com/robotel-limited/robo-cortex/tree/main/benchmark-results-20260718), [scripts/benchmark/](https://github.com/robotel-limited/robo-cortex/tree/main/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](https://github.com/robotel-limited/robo-cortex/blob/main/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.
 
 ---
 

{robo_cortex-0.4.0 → robo_cortex-0.4.2}/src/robo_cortex/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.4.0"
+__version__ = "0.4.2"
 
 from robo_cortex.sdk import RoboCortex, retrieve, record, search
 

{robo_cortex-0.4.0 → robo_cortex-0.4.2}/src/robo_cortex/mcp_server.py

@@ -26,7 +26,10 @@ description and dropped the prompt-injection framing below. Caught by
 testing the actual mechanism before relying on it, not by inspection.
 """
 
+from typing import Annotated
+
 from mcp.server.fastmcp import FastMCP
+from pydantic import Field
 
 from .core.errors import NotFoundError
 from .core.evidence import attach_evidence as core_attach_evidence
@@ -85,6 +88,20 @@ _VERIFY_EVIDENCE_DESCRIPTION = (
     "when this is called). `scope` disambiguates an evidence_id that "
     "collides between the repo and global stores. " + _COMMAND_IS_DATA
 )
+_LIST_AFFECTED_DESCRIPTION = (
+    "Report which stored memories a git diff puts at risk because it touches "
+    "a code file they are anchored to -- the proactive half of invalidation. "
+    'Returns {"data": [{"id", "statement", "reason"}], "matched": N}; each '
+    "`reason` names the offending path and diff source, e.g. "
+    "`path_changed:src/scanner.py@working_tree`. Terminal-status memories "
+    "(superseded/invalidated/abandoned/archived) are excluded -- already "
+    "history. Use it when you are about to change, or have just changed, code "
+    "and want to know which memories that change endangers: it is "
+    "diff-driven, mapping a code delta to the memories that depend on it -- "
+    "unlike retrieve_context (natural-language task -> context pack) and "
+    "search_memory (keyword query). Runs the staleness refresh first, so "
+    "drift already committed is flagged before the diff-scoped report."
+)
 
 
 def build_server(repo_arg: str | None = None) -> FastMCP:
@@ -221,18 +238,39 @@ def build_server(repo_arg: str | None = None) -> FastMCP:
             status=status, limit=limit, global_conn=global_conn,
         )
 
-    @server.tool(name="list_affected")
+    @server.tool(name="list_affected", description=_LIST_AFFECTED_DESCRIPTION)
     def list_affected_tool(
-        diff_range: str | None = None,
-        staged: bool = False,
-        working: bool = False,
+        diff_range: Annotated[
+            str | None,
+            Field(
+                description=(
+                    "Optional committed range in git syntax, e.g. 'HEAD~3..HEAD'. "
+                    "Memories are compared against the range's end content. Takes "
+                    "precedence over `staged`/`working` if more than one is given."
+                )
+            ),
+        ] = None,
+        staged: Annotated[
+            bool,
+            Field(
+                description=(
+                    "Inspect only staged changes (`git diff --cached`). "
+                    "Ignored if `diff_range` is set."
+                )
+            ),
+        ] = False,
+        working: Annotated[
+            bool,
+            Field(
+                description=(
+                    "Inspect only unstaged working-tree changes (`git diff`). "
+                    "Ignored if `diff_range` is set. When `diff_range`, `staged`, "
+                    "and `working` are all omitted, staged and unstaged changes are "
+                    "inspected together (`git diff HEAD`)."
+                )
+            ),
+        ] = False,
     ) -> dict:
-        """What does a diff put at risk -- the proactive half of
-        invalidation. Default (all omitted): working tree + staged combined.
-        Runs the staleness refresh first, so anything already committed
-        since the last check is flagged/healed for real before the
-        diff-scoped report is computed.
-        """
         return core_affected(
             local_conn, repo_root, diff_range=diff_range, staged=staged, working=working
         )

{robo_cortex-0.4.0 → robo_cortex-0.4.2}/tests/test_smoke.py

@@ -2,4 +2,4 @@ from robo_cortex import __version__
 
 
 def test_version_is_set():
-    assert __version__ == "0.4.0"
+    assert __version__ == "0.4.2"