Codebase memory

Index a project's files locally and reuse the index for code search and conversation context.

Codebase memory

Chapter 044Core runtimeGuideIndex

01Orientation

MTP stores a project index in .mtp/memory/codebase.sqlite. This is a local SQLite index of file metadata, chunks, deterministic embeddings, and conversation summaries. It does not require an embedding API.

Use this when

Index a project's files locally and reuse the index for code search and conversation context.

Enable and inspect
Use it in a terminal chat
Troubleshooting

02 / syntax starter

mtp codebase memory --path ./my_agent --on
mtp codebase status --path ./my_agent
mtp codebase memory --path ./my_agent --off

03 / manual

Read the system

The complete source manual—syntax, examples, linked references, edge cases, and implementation notes.

Documentation index ↗

01Enable and inspect

MTP stores a project index in .mtp/memory/codebase.sqlite. This is a local SQLite index of file metadata, chunks, deterministic embeddings, and conversation summaries. It does not require an embedding API.

Enable and inspect

bashmtp codebase memory --path ./my_agent --on
mtp codebase status --path ./my_agent
mtp codebase memory --path ./my_agent --off

The scan skips generated folders such as .git, .venv, node_modules, dist, and caches, along with secret-like files. Turning memory off changes the enabled flag. It does not delete the index.

02Use it in a terminal chat

Use it in a terminal chat

text/codebase memory on
/codebase status

When memory is enabled, project.inspect, fs.search, fs.grep, and codebase.search use the index and refresh changed files before retrieval. Each chat uses its own workspace. Switching chats restores its workspace and draft, and a background scan does not replace the conversation view.

03Troubleshooting

Troubleshooting

Check /cd and /codebase status if search results describe the wrong project. Run another scan after a large checkout change. Keep the index inside the intended project root. Deterministic matching helps retrieve relevant chunks, but it does not guarantee that every relevant file appears in a result.

See CLI and TUI operating guide.

recorded examples

See MTP in use

Captured output and terminal screens from MTPX 0.1.37. These offline demos make no cloud requests.

videoIndex a workspace

Enable codebase memory and inspect its status. The scan writes a local SQLite index inside the demo project.

Read the guide ↗

Read

Understand where Codebase memory sits in the agent loop before adding abstractions.

Wire

Connect the smallest useful provider, registry, store, or event stream first.

Observe

Expose events, logs, results, and failure states while the runtime is still moving.

Harden

Add policy, tests, retries, and audit traces after the behavior is visible.

Next docAgent OS