# Memory linked to code for coding agents

> Source: https://clickhouse.github.io/loom/use-cases/memory-linked-to-code/ (Markdown: https://clickhouse.github.io/loom/use-cases/memory-linked-to-code.md)

Loom links coding agents' memories to the functions, classes and files they name, follows
them through refactors, and flags a memory when its code changes. By default, search leaves
out a memory whose code is all gone unless a person pinned, locked or verified it, and every
read that serves a lesson says when its code changed or is gone. It runs over MCP, HTTP and
the SDKs on the repositories a self-hosted Loom indexes (the
[code index](https://clickhouse.github.io/loom/use-cases/code-intelligence.md), `LOOM_CODE_INGEST_ENABLED=true`), and the
`memory_code_links` worker that keeps the links is on by default.

## What you get

- **Lessons attached to the code they are about.** A memory tagged `repo:<id>` (the Claude
  Code and Codex plugins tag what their hooks capture) or written in the repository's code
  namespace is linked to each definition (function, class or other symbol) it names in
  backticks, or anywhere in its text as `A::b` or a call (`a.b()`, `name()`), that resolves
  to exactly one place (an unqualified name needs four or more characters); to definitions
  in the files it lists that it names by a bare camelCase or snake_case word; and to each
  file it lists that holds none of them. A qualified name not on trunk yet links if it
  merges within `LOOM_MEMORY_CODE_LINKS_PENDING_DAYS` (14 days).
  [Memories linked to code](https://clickhouse.github.io/loom/concepts/memory.md#memories-linked-to-code)
- **Links that follow refactors.** On every indexed commit, each link reads `fresh`,
  `moved`, `changed` (naming the commit that changed it), `unresolved` or `missing`. A link
  records the definition's tokens, so whitespace, comments and most formatter changes leave
  it `fresh`. [Link states](https://clickhouse.github.io/loom/concepts/memory.md#memories-linked-to-code)
- **Stale memories handled the way you choose.** The namespace's
  [`code_change_policy`](https://clickhouse.github.io/loom/reference/operations/namespace.md#namespaceregister) decides:
  `retire_removed` (the default) leaves a memory whose code is all gone out of search and
  flags changed code; `flag` only flags; `revise` also leaves gone-code memories out, and
  has the model check a changed one's claim against the old and new code: one that still
  holds is re-anchored, and a contradicted one gets a suggested correction. A memory a
  person pinned, locked or verified is never left out. Under every policy, search usually
  ranks a memory whose code changed below the next three results instead of hiding it; a
  held memory and a row found by name keep their place. Loom never rewrites the memory
  itself. [Policies](https://clickhouse.github.io/loom/concepts/memory.md#memories-linked-to-code)
- **Lessons wherever the agent reads code.** `code.symbol` returns the memories linked to a
  definition as `lessons`; `code.search`, `code.callers`, `code.callees`, `code.impact`,
  `code.outline` and a task's `code.context_pack` attach the lessons for the files they
  return; each lesson carries its link state. The Claude Code and Codex hooks show a file's
  memories (`memory.for_file`) before an agent edits it, and the Cline hooks when it reads
  or edits one. [`code.symbol`](https://clickhouse.github.io/loom/reference/operations/code.md#codesymbol) ·
  [Claude Code plugin](https://clickhouse.github.io/loom/features/integrations/claude-code.md) ·
  [Codex plugin](https://clickhouse.github.io/loom/features/integrations/codex.md) ·
  [Cline hooks](https://github.com/ClickHouse/loom/blob/main/integrations/cline/README.md) (experimental)
- **Shared with the team.** Lessons are read from the repository's code namespace and the
  namespaces the call names (over MCP, the caller's own by default), so a lesson saved in
  the repository's code namespace reaches every agent that may read that namespace (a token
  narrowed to its own user or session reads no lessons).
  [Memories linked to code](https://clickhouse.github.io/loom/concepts/memory.md#memories-linked-to-code)
- **Branches read their own code.** On another branch, a lesson is checked against that
  branch's own definition, so a release branch that still has the old text reads `fresh` (on
  a host with `LOOM_GIT_HISTORY=none`, which has no git mirror, a lesson carries trunk's
  state). [Memories linked to code](https://clickhouse.github.io/loom/concepts/memory.md#memories-linked-to-code)
- **Documents beside the code.** Documents from a source registered on the repository's code
  namespace (its trunk's) carry the repository's tag, so searches over the repository read
  them with its code (the sync worker needs `LOOM_KNOWLEDGE_SOURCE_SYNC_ENABLED`).
  [Document sources](https://clickhouse.github.io/loom/features/knowledge.md#document-sources)
- **A review list.**
  [`namespace.validate`](https://clickhouse.github.io/loom/reference/operations/namespace.md#namespacevalidate) lists the
  memories whose code changed, was not found again or is gone, and the dashboard shows each
  memory's links and their state.

![A memory's detail in the dashboard: its linked code, one definition current and one changed since a commit](https://clickhouse.github.io/loom/assets/screenshots/memory-linked-code.webp)

## Start

[Quickstart](https://clickhouse.github.io/loom/getting-started/quickstart.md) boots Loom, and
[adding repositories](https://clickhouse.github.io/loom/features/code-index/repositories.md) turns the code index on for a
repository. Connect your coding agent with its plugin or over MCP
([connect a coding agent](https://clickhouse.github.io/loom/getting-started/connect-a-coding-agent.md)). Save a lesson that
names a definition of four or more characters in backticks or as a call (`` `name()` ``), or
a qualified one such as `` `Reader.run` ``. The Claude Code and Codex plugins tag what their
hooks capture with `repo:<id>`, and the session primer names the id
([how it is derived](https://clickhouse.github.io/loom/features/integrations/claude-code.md#configuration)). A lesson the
agent saves itself with `loom_memory_set` links when it carries that tag
(`tags: ["repo:<id>"]`) or is written in the repository's code namespace; any client can do
either. Over HTTP (or `agent.call` in the Python SDK), a lesson saved in your own namespace
is read only when the call names that namespace in `lesson_namespaces`. Each link pass links
writes at least 60 seconds old and passes run every 60 seconds, so once trunk is indexed,
`code.symbol` on that definition returns the lesson under `lessons` within about two
minutes.

## Check a lesson after a code edit

On the repository's indexed trunk, save a lesson such as `` `fetch_page()` retries on code 115 ``
with the repository tag or in its code namespace, as above. Use a name that resolves to
one definition. After the link pass, read that definition with `code.symbol` and look for
the saved memory under `lessons`. When included, it carries `code_state: "fresh"`.
Include the memory's namespace in `lesson_namespaces` when the call needs it.

Change an expression in the function's body, such as `return url` to `return url.strip()`,
and commit it on trunk. After the index and link worker process that commit, read the
definition again in the same trunk namespace. Under the default policy, a returned
lesson carries `code_state: "changed"`; `changed_since` names the indexed
commit. This marks changed code, not a judgment that the lesson is false. Read the
current body before applying it. Uncommitted editor changes do not trigger this check.

Symbol cards cap the lessons they return and can omit the saved lesson. If it is absent,
use `memory.get` to inspect that memory's `code` links and their states.

The existing `test_memories_follow_their_code`
[integration regression](https://github.com/ClickHouse/loom/blob/main/tests/integration/test_memory_code_links.py)
checks these states across commits. It also checks a pure move (`moved`), removed code
(`missing`) and a release branch whose unchanged definition still reads `fresh`.

The packaged [MCP smoke](https://github.com/ClickHouse/loom/blob/main/scripts/gates/docker_code_smoke.py)
saves a lesson, verifies `fresh`, commits a body edit and waits for the indexing and link
workers to return `changed` with that exact commit. The
[quickstart harness](https://github.com/ClickHouse/loom/blob/main/scripts/gates/docker_quickstart_smoke.py)
restarts the Loom service, checks the link again and deletes the test memory.
[CI](https://github.com/ClickHouse/loom/actions/workflows/docker-smoke.yml) runs these checks
on amd64 and arm64 with authentication off, a local embedder and a fake model provider.
These checks verify code-link state; authenticated clients, answer quality and agent
tool selection are not tested.

For removal, held-memory exceptions and model-backed revision, see the
[link policies](https://clickhouse.github.io/loom/concepts/memory.md#memories-linked-to-code).

Some ops on this page are marked experimental on the [status page](https://clickhouse.github.io/loom/reference/status.md).
