# Korium:Code

Someone asks you to change the refund calculation. Before editing, you need to find the calculation and understand the decisions behind it. Korium:Code finds the source location; Korium memory gives you the reasons and earlier lessons.

## A map of the code, not a second copy of it {#map}

The indexer runs on the machine holding your repository. It extracts named symbols such as functions, classes and methods, with their kinds, file paths, line ranges and fingerprints. Korium stores that map against a repository and commit.

Source bodies stay local. A search returns locations for the assistant to inspect in the checkout it is working on. Symbol names and paths can still reveal sensitive information, so review the map before uploading it.

## Build the map once {#setup}

Follow [Index your code](indexing-your-code.html) to install the Mac CLI, sign in, inspect the extracted cards and publish the index. Start with a repository you are allowed to index. From that repository, the local preview is:

```
korium-cli index --dry-run
```

This does not upload anything and does not require a sign-in. Once you have reviewed what will be sent, the indexing guide takes you through publication and a known-symbol search. Upload acceptance alone is not proof that a new commit is searchable.

## Ask two different questions before changing code {#use}

This refund example is an illustration. Replace the scope and symbol names with ones from your project.

1. **Ask memory why.** Search for the refund decision, known edge cases and rejected alternatives. Read the evidence behind the answer.
2. **Ask the code index where.** Search for the calculation’s likely identifier. Open the returned file and line range locally.
3. **Check what is actually there.** Compare the indexed commit with your checkout, then read the implementation and its tests before proposing a change.

```
Search Korium under billing.refunds for the refund policy and
any earlier mistakes. Show the sources.
Then locate RefundPolicy or calculateRefund in the code index.
Check the returned commit against this checkout and read the
implementation and tests. Explain the change before editing.
```

If you are searching from the terminal, the code lookup is:

```
korium-cli search "RefundPolicy calculateRefund"
git rev-parse HEAD
```

The first line of the search answer names the branch whose index answered and its indexed commit. Each branch has its own index: the search reads the branch you are on when Korium holds an index for it, and the repository’s trunk otherwise. A different commit does not make the answer useless, but its locations need checking against your files. The index does not certify uncommitted edits.

## Let an assistant look up code through MCP {#mcp}

The MCP tool is `code_locate`. Use the canonical repository identity reported by the CLI and the checkout SHA from `git rev-parse HEAD`, rather than guessing from a repository’s display name. Name the branch to search that branch’s index; without one, the trunk answers. The assistant still needs authorized local access to read the returned source.

When the checkout’s index is missing or behind, the answer tells the assistant what to do: run `korium-cli index` in the checkout, which indexes the branch the checkout is on. Korium also says this in the instructions it sends an assistant when it connects. An assistant that can run commands in your checkout can then bring the index up to date itself and search again.

The [tool reference](tool-reference.html) describes the request. `agent_search` and `code_locate` are different searches: one retrieves what was learned, the other locates code. Neither should stand in for the other.

## Know when to use a local text search {#misses}

Korium indexes symbols in Elixir / Rust / Swift / Python / shell / JavaScript / TypeScript / Go / Java / Ruby. HTML, Markdown, JSON, YAML, SQL and Terraform are not part of that symbol index. Use a local text search for those files.

For supported code, search toward the identifier you expect to find, not a paragraph describing the whole task. If a lookup misses, check the repository, commit and result reason before assuming the code is absent. Rephrasing cannot find a file type the index does not contain.

## Keep the map and the explanation useful {#finish}

After the change, run the relevant tests and save the decision or lesson in memory, with the issue or test as evidence. Keep code indexing as a separate step. A successful upload does not capture why you made the change.

To keep each branch’s index current as the code changes, use [Git / GitHub hooks](git-and-github.html) or the [Codex](codex.html#hooks) and [Claude Code](claude-code.html#hooks) hook guides. The next person should be able to find both the implementation and the reason for it.