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.