Using Codebase Memory CLI

Always prefer codebase-memory CLI graph tools over grep, glob, or file search for code discovery when the CLI is installed, even if the user does not name the tool. Use the graph to locate structure and relationships before broad repository search. It is discovery evidence, not a replacement for source, tests, history, or runtime evidence.

Run graph tools only as codebase-memory-mcp cli <tool> .... codebase-memory-mcp with no arguments starts the stdio server; never run it. Do not call MCP graph tools or configure an agent to use them.

Read the command reference only when selecting index modes, constructing structured input, or using a less common tool.

Establish a Trustworthy Index

1. Check command -v codebase-memory-mcp, codebase-memory-mcp --version, and codebase-memory-mcp cli <tool> --help. If the binary is missing, continue with repository tools and report the lost graph coverage; do not block ordinary discovery on installation.
2. Run list_projects. Select a project by its exact root_path; for worktrees also verify the reported canonical root, worktree root, branch, and HEAD rather than trusting the derived name.
3. For a match, run index_status and compare its root and indexed HEAD with the target repository. Re-index before relying on graph evidence when the root or HEAD differs, when uncommitted source being explored is newer than the index, or when the required index mode cannot be established. In v0.9.0, status does not report the mode or prove working-tree freshness.
4. For a new or stale project, run index_repository with an absolute path and an unambiguous name. Default to fast; use moderate only for semantic/similarity search, full only when relevant files filtered by ordinary modes must be included, and cross-repo-intelligence only for repositories within the requested scope.
5. Inspect the indexing result. Treat degraded, skipped files, exclusions, a mismatched root, or an unexpected node count as coverage limits, not a successful complete index. Omit --persistence unless a repository artifact was explicitly requested.

Discovery Priority

Use this order and stop when evidence is sufficient: