Skip to content

NetFabric/NetFabric.Numerics / .agents/skills/codebase-memory

codebase-memory

Flagged

Install, verify, and integrate codebase-memory-mcp (CBM) — a local C binary indexing a codebase into a persistent knowledge graph (functions, classes, call chains, routes) queryable via 15 tools. USE FOR: creating or editing any agent/skill/prompt/subagent that reads, searches, or reasons about a codebase — CBM's CLI must replace grep/ripgrep/glob-and-read exploration for structural questions (who calls X, dead code, architecture overview, diff impact, Cypher queries); checking whether `codebase-memory-mcp` is installed; installing/updating it; checking whether a project's index is fresh/in sync (`index_status`); choosing CLI vs MCP (always prefer the CLI, far fewer tokens per call than MCP); picking the right CBM tool per workflow stage (discovery, verification, implementation, review). DO NOT USE FOR: semantic/business-logic code review; non-code repos with nothing to index.

FileKindSize
SKILL.mdskill md4.1 KB
references/installation.mdmarkdown5.4 KB
references/integration-guide.mdmarkdown6.5 KB
references/tools.mdmarkdown5.8 KB

references/integration-guide.md

View on GitHub
# Wiring CBM into an Agent, Skill, or Prompt

When you create or edit an agent, subagent, skill, or prompt that operates on a codebase, replace `grep`/`ripgrep`/glob-and-read exploration with CBM CLI calls. This mirrors CBM's own documented agent-integration model (Scout/Verify/Auditor tiers, README "Multi-Agent Support"), generalized to any workflow stage.

## Why this replaces grep/search

A single graph query answers what would otherwise take a cascade of `grep → read file → grep again → read more files`. `search_graph`/`query_graph` return structured, pre-resolved relationships (import-aware, type-inferred call edges) that a text search cannot reconstruct — e.g. "who calls this function across packages" or "what does this route handler call" is one `trace_path`/`query_graph` call versus dozens of file reads.

Before wiring in CBM, confirm it applies: [installation.md](installation.md) covers checking install state and index freshness. A stale or absent index still requires `index_repository` first — CBM cannot answer structural questions about code it hasn't parsed.

## Mandatory readiness owner and preflight

The integrated agent must prove CBM readiness before its first codebase query.
For a multi-agent squad, the orchestrator owns this preflight and completes it
before dispatching the planner or any specialist; do not assume each child will
independently notice a missing binary. Give that orchestrator narrowly scoped
shell access for this preflight even when it delegates every other command.

1. Run `command -v codebase-memory-mcp && codebase-memory-mcp --version`.
2. If absent, install it using the platform command in
   [installation.md](installation.md), update `PATH` when needed, and rerun the
   version check. Do not continue if installation fails.
3. Run `codebase-memory-mcp cli index_status --project <project-name>`.
4. If the project is absent, stale, or not `ready`, run:

   ```bash
   codebase-memory-mcp cli index_repository \
     --repo-path "$PWD" \
     --name <project-name>
   ```

5. Run `index_status` again and continue only after it reports `ready`.
6. Pass the successful version and status output into child dispatches. Require
   actual CBM command output from agents that claim to have used CBM; prompt
   text mentioning CBM is not usage evidence.

Specialists should recheck `index_status` before structural work because edits
made by an earlier node can stale the graph. They use the same index-and-recheck
sequence when needed, but installation remains the orchestrator's responsibility
in a squad.

## Per-stage tool selection

| Stage | Goal | CLI tool(s) | Why |
| --- | --- | --- | --- |
| Setup | Confirm CBM is usable before relying on it | `index_status`, `list_projects` | Fails fast if the project isn't indexed or the index is stale, instead of silently falling back to slower search. |
| Discovery / scout | Fast, provisional orientation in an unfamiliar area of the codebase | `get_graph_schema`, `get_architecture`, `search_graph` (incl. `semantic_query`) | Cheap, broad calls that establish what exists (languages, packages, routes, hotspots) before narrowing — no absence or exhaustive-impact claims yet. |
| Locating symbols | Find the exact qualified name/location before acting on it | `search_graph` (`name_pattern`, `label`, `file` filters), `search_code` | `get_code_snippet` and `trace_path` require exact names; `search_graph` is how you discover them first. |
| Understanding relationships | Who calls this, what does this call, what inherits/implements it | `trace_path` (BFS, depth 1-5), `query_graph` (Cypher for multi-hop or filtered patterns `search_graph` can't express) | Import-aware, type-inferred resolution across files/packages in one call, replacing a manual call-chain grep. |
| Reading implementation | Get the actual source once the target symbol is confirmed | `get_code_snippet` | Reads by qualified name — no need to grep a file path first. |
| Verification / task-directed work (default tier) | Before making a claim or edit, confirm evidence is complete for the files in scope | `check_index_coverage` for every cited path, then `get_code_snippet`/`trace_path` for exact source | A clean graph result only means "no recorded gap" — read flagged/skipped ranges directly from source before asserting completeness or absence (e.g. dead code, "no callers"). |
| Change impact | What does an uncommitted diff affect, and how risky | `detect_changes` | Maps the diff to affected symbols and blast radius with risk classification — one call instead of manually tracing every changed function's callers. |
| Dead code / cleanup | Find unused functions before removing or flagging them | `query_graph` with `WHERE NOT EXISTS { (f)<-[:CALLS]-() }`, or the dedicated dead-code detection | Graph-native exclusion of entry points (route handlers, `main()`, framework decorators) that a naive "zero grep hits" check would misclassify. |
| Cross-service / architecture review | HTTP routes, gRPC/GraphQL/tRPC, pub-sub channels, cross-repo links | `get_architecture`, `query_graph` (`HTTP_CALLS`/`ASYNC_CALLS`/`EMITS`/`LISTENS_ON`/`CROSS_*` edges) | These relationships are cross-file/cross-service by nature; only the graph has them pre-resolved with confidence scoring. |
| Broader / auditor-tier review | Bounded-scope, complete-pagination verification across a wider area | `search_graph`/`query_graph` with explicit pagination, `check_index_coverage` for the full relevant scope | Matches CBM's own Auditor tier: complete relevant pagination and explicit unresolved limitations, not a sampled pass. |
| Architecture decisions | Persist or retrieve the rationale behind a structural decision | `manage_adr` | Keeps design rationale attached to the graph across sessions/teammates instead of a separate untracked doc. |

## Authoring checklist

When an agent/skill/prompt you're writing or editing touches a codebase:

1. State explicitly that CBM's CLI is the required exploration path, not `grep`/`find`/reading files ad hoc.
2. Assign the install/index readiness preflight to the integrated agent, or to the orchestrator before delegation when the target is a squad.
3. Require a successful version check and a final `index_status: ready`; after indexing, always check status again.
4. Match the tool to the stage using the table above, narrowest call first (schema/architecture before deep traversal).
5. Require `check_index_coverage` before any negative claim ("no callers", "dead code", "nothing uses this").
6. Only fall back to a raw file read/grep for content CBM does not index as a graph relationship (e.g. reading a config value, a comment, or a non-code text file).
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 319kUpdated Claude CodeCodexVerifiedInstall