# Memory

The worst part of working with an agent is that it forgets. Close the chat and the next session starts cold — you re-explain your stack, your conventions, the quirk in that one file. V3Code is built so that never happens, and it does it without stuffing everything into the model's context.

## The idea: never forgets ≠ never forgets *on the wire*

"Never forgets" is a **pull guarantee, not a push burden**. Everything the agent ever saw — every prompt, reply, tool result, edit, and decision — is written to disk and instantly recallable. That does **not** mean it's all shoved into the model every turn. The opposite: the agent holds only the **live task** in context and pulls the rest the instant it needs it.

A chat assistant's job is the conversation, so it clings to the transcript. An editor's job is your **code and your current intent** — the conversation is scaffolding. So V3Code keeps the live wire small *because* nothing is lost and recall is excellent. This also dodges "context rot": a stuffed context window makes a model perform worse, not better, so bounded-but-generous beats racing toward a million tokens.

## The tiers

### Native window

The recent raw turns the model holds itself. Cheapest, highest-fidelity memory there is — V3Code doesn't interpose on it.

### Session digest

A running fact-sheet of the middle turns that scrolled off. Once it exists it stays on the wire for the rest of the session — the agent's own memory of what it already did.

### Cross-session memory

Workspace facts, symbol notes, past sessions, other projects. Salience-ranked, scoped to what you're touching, mostly pulled on demand.

### Shadow floor

A raw, append-only record of every event. Never pruned. The break-glass guarantee behind "never forgets" — always recallable, never auto-injected.

## What persists across sessions

- **Workspace memory** — decisions, conventions, and notes tied to a project, surfaced when you're in that project. Symbol notes live in `.v3code/notes.json` (see [Context Bridge](/editor/context-bridge)).
- **Global profile** — style and preferences that travel with you across every project.
- **The full record** — anything condensed or elided off the wire is still retrievable by the agent on demand; decay changes *ordering*, never what's on disk.

## How the agent keeps the wire lean

As a session grows, V3Code intervenes cheapest-first: hold the raw thread while it fits, elide old bulky tool outputs, then fold the conversation middle into the running digest only if still over budget — and it compacts *rarely*, near a large effective-context ceiling, not on every turn. Human-authored and test-verified facts are treated as evergreen.

> Tip:
>
> Tell the agent to **remember** something directly — a convention, a gotcha, a decision *and the reason behind it*. The reason is the valuable part; save the why, not just the what, and it carries forward.

## Memory that follows your code

V3Code's memory isn't a flat list — notes are **pinned to your code's structure** and resurface by walking it. This is the "graph-anchored" part, and it's what makes memory feel like the agent just *knows* your project.

- **The graph.** The native symbol sidecar parses every file (tree-sitter) into a code graph — files → the symbols they define → the files that reference them. That's the real dependency structure of your project.
- **Anchoring (write).** When the agent saves a memory about code, it's pinned to the relevant file/symbol nodes in that graph. Save it again and it's re-confirmed — its confidence goes up.
- **The ripple (read).** When a prompt is assembled, V3Code looks at the files you're actively working in and recalls notes *near* them — rippling outward through the graph (the file's symbols, the files that reference them, their neighbors). A note on the exact file arrives at full strength; one a couple of hops away still surfaces, just discounted.

The payoff: **memory follows code structure, not keywords.** Open a file and the agent automatically remembers the decisions, gotchas, and history attached to that neighborhood of the codebase — including notes on files it hasn't even opened — without running a single search. And it gets richer on its own: as the agent explores code, what it learns is recorded automatically, so the map of your project deepens just from working in it.

> Note:
>
> Honest limits: this pulls from your few most-active files (a handful of notes each) per prompt; it uses the symbol sidecar (without it, memory gracefully falls back to the editor's own store); and every workspace starts empty — nothing is pre-populated.

> Note:
>
> Working in a blank/greenfield folder? V3Code deliberately suppresses cross-project memory there, so the agent grounds in the empty project in front of it instead of hallucinating off unrelated history. Everything stays recallable on demand.