> For the complete documentation index, see [llms.txt](https://docs.codna.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codna.ai/concepts/memory.md).

# Code Memory

Codna keeps a local semantic index of your repository so it — and any AI client connected through [MCP](/guides/mcp.md) — can recall the most relevant symbols for a query without re-reading the codebase. It's powered by Telys, Codna's memory kernel, bundled in the wheel.

{% hint style="success" %}
Memory runs fully offline with zero configuration. The Telys license is baked into the wheel, so you never manage a separate one.
{% endhint %}

## Turn it on

```bash
codna login
```

`codna login` authorizes this device through Codna's accounts portal and receives a device-scoped offline license. It's free for one device. Base `codna` also ships with an OEM license, so memory works before you log in; the device login adds a per-device entitlement that takes precedence.

Flags:

* `--token <tok>` — headless token (or `$TELYS_TOKEN`); skips the browser.
* `--no-browser` — print the verification URL and code to authorize elsewhere.
* `--no-install` — authorize and register only; skip provisioning the runtime.

## The store

Codna builds a per-repository index in `.codna-memory/` at the repo root:

| File                  | Purpose                                                           |
| --------------------- | ----------------------------------------------------------------- |
| `codna_memory.json`   | Index-run record: commit SHA, branch, timestamp, vector-space id. |
| `content_hashes.json` | Per-symbol content hashes for incremental re-indexing.            |
| `repo_symbols/`       | The Telys collection (the vector index).                          |

The index persists across runs and refreshes when `HEAD` moves, re-embedding only changed symbols. Add `.codna-memory/` to `.gitignore`.

{% hint style="info" %}
As an [MCP server](/guides/mcp.md), Codna stores recall indexes outside your checkout, under `~/.codna/telys-memory/mcp/` (override with `CODNA_TELYS_MEMORY_ROOT`).
{% endhint %}

## Recall

The `codna_recall` MCP tool returns the most relevant symbols for a query:

| Parameter  | Default      | Meaning                            |
| ---------- | ------------ | ---------------------------------- |
| `repo`     | `"."`        | Repository path.                   |
| `query`    | *(required)* | What you're looking for.           |
| `service`  | `""`         | Optional service/partition filter. |
| `language` | `""`         | Optional language filter.          |
| `final_k`  | `8`          | Symbols to return.                 |

It returns `symbols` (each with `id`, `score`, `symbol_type`, `path`), an `explain` breakdown, and `candidate_count`. It builds the index on first call if empty.

Ranking blends lexical and semantic signals (default: `alpha 0.7`), down-weighting test symbols for non-test queries. Without the WordLlama reranker installed, it falls back to lexical ranking.

## Tuning

| Variable                       | Default  | Effect                                                                         |
| ------------------------------ | -------- | ------------------------------------------------------------------------------ |
| `CODNA_MEMORY_RERANK`          | `blend`  | `blend` \| `wordllama` \| `lexical`/`off`.                                     |
| `CODNA_MEMORY_RERANK_ALPHA`    | `0.7`    | Lexical vs. WordLlama weight (0–1).                                            |
| `CODNA_MEMORY_RERANK_K`        | `40`     | Size of the reordered candidate pool.                                          |
| `CODNA_MEMORY_TEST_DOWNWEIGHT` | `0.85`   | Test-symbol multiplier for non-test queries (`1.0` = off).                     |
| `CODNA_MEMORY_EMBED`           | *(auto)* | `local` forces the in-process embedder; `remote` requires the engine embedder. |
| `CODNA_MEMORY_EMBED_MODEL`     | *(auto)* | Override the embedding model id.                                               |
| `CODNA_MEMORY_EMBED_DIM`       | `1024`   | Embedding dimension.                                                           |

The semantic reranker needs the optional dependency: `pip install "codna[memory-rerank]"`.

## Next steps

* [Language support](/concepts/languages.md) — which languages the extractor indexes.
* [MCP Server](/guides/mcp.md) — expose `codna_recall` to a client.
* [Installation](/getting-started/installation.md) — the `codna[memory]` extras.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.codna.ai/concepts/memory.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.