---
name: codebase-memory
description: "Use the codebase knowledge graph for structural code queries — explore the codebase, understand the architecture, what functions exist, show me the structure, who calls this function, what does X call, trace the call chain, find callers of, show dependencies, impact analysis, dead code, unused functions, high fan-out, refactor candidates, code quality audit, graph query syntax, Cypher query examples, edge types, how to use search_graph."
---

# Codebase Memory — Knowledge Graph Tools

The Pi bridge exposes these as native `cbm_*` tools, while the official CBM CLI remains the semantic authority. Graph tools return precise structural results in ~500 tokens vs ~80K for grep. Advanced tools are loaded on demand with `cbm_search_tools`.

## Quick Decision Matrix

| Question | Tool call |
|----------|----------|
| Who calls X? | `cbm_trace_path(direction="inbound")` |
| What does X call? | `cbm_trace_path(direction="outbound")` |
| Full call context | `cbm_trace_path(direction="both")` |
| Find by name pattern | `cbm_search_graph(name_pattern="...")` |
| Dead code | `cbm_search_graph(max_degree=0, exclude_entry_points=true)` |
| Cross-service edges | `cbm_query_graph` with Cypher, after `cbm_search_tools` if needed |
| Impact of local changes | `cbm_detect_changes`, after `cbm_search_tools` if needed |
| Risk-classified trace | `cbm_trace_path(risk_labels=true)` |
| Text search | `cbm_search_code` or Grep |
| Read several symbols | `cbm_get_code_snippets` |

## Exploration Workflow
1. `cbm_list_projects` — check if project is indexed
2. `cbm_get_graph_schema` — understand node/edge types, loading it with `cbm_search_tools` when inactive
3. `cbm_search_graph(label="Function", name_pattern=".*Pattern.*")` — find code
4. `cbm_get_code_snippet(qualified_name="project.path.FuncName")` — read source

## Tracing Workflow
1. `cbm_search_graph(name_pattern=".*FuncName.*")` — discover exact name
2. `cbm_trace_path(function_name="FuncName", direction="both", depth=3)` — trace
3. `cbm_detect_changes()` — map the current git diff to affected symbols, loading it with `cbm_search_tools` when inactive

## Quality Analysis
- Dead code: `cbm_search_graph(max_degree=0, exclude_entry_points=true)`
- High fan-out candidates: `cbm_search_graph(min_degree=10, relationship="CALLS")`, then `cbm_trace_path(direction="outbound")`
- High fan-in candidates: `cbm_search_graph(min_degree=10, relationship="CALLS")`, then `cbm_trace_path(direction="inbound")`

## Native CBM Tools
The bridge uses the `cbm_` prefix to avoid collisions with other Pi packages:

`cbm_search_graph`, `cbm_search_code`, `cbm_trace_path`, `cbm_get_code_snippet`,
`cbm_get_code_snippets`, `cbm_list_projects`, `cbm_index_status`,
`cbm_search_tools`, plus lazy `cbm_index_repository`, `cbm_query_graph`,
`cbm_get_graph_schema`, `cbm_get_architecture`, `cbm_check_index_coverage`,
`cbm_detect_changes`, `cbm_manage_adr`, and `cbm_ingest_traces`.

`delete_project` is intentionally not exposed as an agent tool.

## Edge Types
CALLS, HTTP_CALLS, ASYNC_CALLS, IMPORTS, DEFINES, DEFINES_METHOD,
HANDLES, IMPLEMENTS, OVERRIDE, USAGE, FILE_CHANGES_WITH,
CONTAINS_FILE, CONTAINS_FOLDER, CONTAINS_PACKAGE

## Cypher Examples (for query_graph)
```
MATCH (a)-[r:HTTP_CALLS]->(b) RETURN a.name, b.name, r.url_path, r.confidence LIMIT 20
MATCH (f:Function) WHERE f.name =~ '.*Handler.*' RETURN f.name, f.file_path
MATCH (a)-[r:CALLS]->(b) WHERE a.name = 'main' RETURN b.name
```

## Gotchas
1. `cbm_search_graph(relationship="HTTP_CALLS")` filters nodes by degree. Load `cbm_query_graph` for exact Cypher inspection.
2. `cbm_query_graph` is bounded by `max_rows`; raise it only when the task needs more data.
3. `cbm_trace_path` needs exact names. Use `cbm_search_graph(name_pattern=...)` first.
4. `direction="outbound"` misses cross-service callers. Use `direction="both"`.
5. Results are bounded by default. Check `has_more` and paginate deliberately.
6. Large results are capped and saved to a temporary file. Request `full_output: true` only when required.