# Codebase Memory

> Use when navigating, indexing, tracing, or comparing local and inspiration repositories through the Codebase Memory MCP knowledge graph.

- Skill: `ryan-brosas/codebase-memory` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ryan-brosas/codebase-memory`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ryan-brosas/codebase-memory/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ryan-brosas (https://skillmd.com/u/ryan-brosas)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ryan-brosas/codebase-memory

---


# Codebase Memory

Codebase Memory is a persistent operational index over explicitly indexed
repositories: conceptually a rebuildable projection of source, safe to
recreate from its canonical repositories. It is not historical experience
memory, not authority for current code, and not required for active-project
orientation. Fovea owns the active working-set map, and direct source owns
truth: confirm exact code in the JetBrains IDE or direct source before
editing or making exhaustive claims.

## Core Principle

A rebuildable cross-repository index, not a default step: the graph is a derived projection of source, never historical memory, confirmed against exact current source and tests before use.

## When to Use / NOT

- **Use when:** the question spans repositories, services, or explicitly indexed repository revisions: finding which indexed project holds a pattern, comparing a reference candidate, cross-service structure, or non-Pi environments where Fovea is unavailable.
- **NOT when:** the active project just needs orientation (use Fovea or direct source). Do not index a current or active owned project merely because the MCP is connected. Index creation requires an explicit user request; a finished project is not ingested by default. Never call `codebase-memory_delete_project` without explicit user approval, and do not write ADRs or ingest traces unless requested (see Boundaries).

## Workflow

Use these steps only for graph-assisted work. If relevant source is accessible
and sufficient, inspect it directly without connecting, listing projects,
requesting architecture, or waiting for an index. Graph coverage/readiness
checks are not applicable to that route; qualify exhaustive claims against
the actual source scope instead.

1. Connect to the `codebase-memory` MCP and read its server instructions.
2. Call `codebase-memory_list_projects` before first use. If the repository is
 absent, use direct source or a project-local reference unless the user
 explicitly requests index creation. Re-index an existing library entry only
 after a named large external update or an explicit request.
3. Orient with `codebase-memory_get_architecture`; request only needed aspects.
4. Find definitions with `codebase-memory_search_graph`. Use natural-language,
 regex-name, or semantic search; narrow before paginating `has_more` results.
5. Trace callers, callees, data flow, or cross-service paths with
 `codebase-memory_trace_path`; follow its cursor until the bounded question is
 answered.
6. Read an exact symbol with `codebase-memory_get_code_snippet` only after
 resolving its qualified name. Use `codebase-memory_search_code` for literals.
7. Before negative or exhaustive claims, call
 `codebase-memory_check_index_coverage` for cited paths/scopes. Fall back to
 JetBrains search or direct source for skipped and partially parsed ranges.
8. Before editing, use `codebase-memory_detect_changes` or a bounded graph trace
 to identify blast radius. After editing, trust source, IDE diagnostics, and
 behavioral checks over stale graph output.

## Inspiration Repositories

Use one indexed project per question. Record project name, root path, branch or
commit, license, exact graph call, and coverage caveats. Compare reference and
active-project capabilities, then choose `adopt`, `adapt`, or `omit` with a
reason. Do not clone or re-index another repository after the evidence gap is
closed.

## Boundaries

- Never call `codebase-memory_delete_project` without explicit user approval.
- Do not write ADRs or ingest traces unless the task explicitly requests it.
- Coverage metadata is best-effort, never proof of completeness.
- Check truncation fields and paginate; do not treat the first page as complete.

## Red Flags

- Treating the graph as source of truth.
- Calling `codebase-memory_delete_project` without approval.
- Treating the first page as complete (truncation fields unchecked).
- Graph-based negative or exhaustive claims without `codebase-memory_check_index_coverage`.
- Cloning or re-indexing another repository after the evidence gap is closed.
- Automatically indexing an active or newly completed owned project.

## Verification

Exact source confirmation before editing; graph coverage checked for cited paths/scopes before graph-based negative or exhaustive claims; blast radius identified before editing; after editing, trust source, IDE diagnostics, and behavioral checks over stale graph output.


## References

N/A, no reference files; this skill is self-contained.