Guidance and Persistent Memory for VT Code

VT Code has two distinct memory surfaces:

• Authored guidance that you write in AGENTS.md and .vtcode/rules/.
• Learned per-repository memory that VT Code stores under your user config directory.

Understanding that split makes it easier to tune prompt quality without mixing durable project instructions with automatically learned notes.

Authored Guidance

Instruction sources and precedence

VT Code loads authored guidance from the lowest-precedence scope to the highest-precedence scope. Later and more specific sources win when they conflict.

Load order	Scope	Location	Purpose
1	User AGENTS.md	~/AGENTS.md, ~/.vtcode/AGENTS.md, ~/.config/vtcode/AGENTS.md	Personal preferences that apply across repositories.
2	User unconditional rules	~/.vtcode/rules/**/*.md or ~/.config/vtcode/rules/**/*.md without paths frontmatter	Always-on personal rules.
3	User matched rules	Same rule roots, but with paths frontmatter that matches the current instruction context	Personal rules that only load for relevant files.
4	Extra instruction files	Paths or globs from agent.instruction_files	Explicitly injected docs such as runbooks or local conventions.
5	Workspace AGENTS.md hierarchy	<repo>/AGENTS.md plus nested AGENTS.md files from repo root to the active instruction scope	Shared project guidance and subsystem overrides.
6	Workspace unconditional rules	<repo>/.vtcode/rules/**/*.md without paths frontmatter	Always-on repository rules.
7	Workspace matched rules	Same workspace rule roots, but with matching paths frontmatter	File- or directory-scoped repository rules.

Path-scoped rules

Rules inside .vtcode/rules/ can use YAML frontmatter with a paths field:

---
paths:
  - "src/**/*.rs"
  - "tests/**/*.rs"
---

# Rust Rules
- Keep changes surgical.

VT Code activates matched rules from the next prompt rebuild when any of these contexts include a matching path:

• the active editor file
• visible editor files
• the active instruction directory
• tracked session file activity such as reads, searches, and edits

Imports and excludes

Authored guidance files can import other files inline with @path/to/file.md.

• Imports expand at the location of the @path line, not at the end of the file.
• Relative imports resolve from the containing file.
• The default recursive import limit is 5, controlled by agent.instruction_import_max_depth.
• Imports are limited to the workspace or VT Code user-config roots.
• Use agent.instruction_excludes to skip specific AGENTS.md or .vtcode/rules/ paths by glob.

Persistent Memory

Persistent memory is VT Code's learned, per-repository memory store. It is separate from authored guidance, and VT Code injects only a compact startup summary after authored instructions.

Storage layout

For each repository, VT Code stores memory under:

~/.vtcode/projects/<project>/memory/

Older VT Code builds stored persistent memory under the general config root on some platforms, such as macOS Application Support. VT Code now migrates the legacy per-repository memory directory into ~/.vtcode/projects/<project>/memory/ the next time that repository memory is resolved.

The directory contains:

memory/
├── memory_summary.md
├── MEMORY.md
├── preferences.md
├── repository-facts.md
└── rollout_summaries/

• memory_summary.md is the source file for the compact startup summary.
• MEMORY.md is the durable registry and index.
• preferences.md stores stable user and workflow preferences.
• repository-facts.md stores grounded repository and tooling facts.
• rollout_summaries/ stores per-session evidence summaries before and after consolidation.

Feature flag

Memories can also be controlled via a Codex-compatible [features] table in vtcode.toml:

[features]
memories = true

When features.memories is true and agent.persistent_memory.enabled is true, VT Code carries durable context from completed threads into future sessions. The [features] toggle acts as the global master switch; the per-repo agent.persistent_memory.enabled gates the actual storage layer.

Memories sub-configuration

The [agent.persistent_memory.memories] table provides Codex-compatible controls for the extraction and injection pipeline:

Key	Type	Default	Purpose
generate_memories	bool	true	Whether completed threads can be stored as memory-generation inputs.
use_memories	bool	true	Whether existing memories are injected into future sessions.
extract_model	string?	agent model	Overrides the model used for per-thread memory extraction.
consolidation_model	string?	agent model	Overrides the model used for global memory consolidation.

Startup behavior

Persistent memory is disabled by default. Enable it with /config memory or by setting agent.persistent_memory.enabled = true.

When agent.persistent_memory.enabled = true, VT Code injects:

1. explicit user instructions
2. authored guidance
3. a compact prompt summary derived from the configured scan of memory_summary.md

The startup scan is controlled by:

• agent.persistent_memory.startup_line_limit
• agent.persistent_memory.startup_byte_limit

Write flow

When agent.persistent_memory.auto_write = true, VT Code writes memory in two phases:

1. Session finalization writes one rollout summary into rollout_summaries/.
2. Consolidation merges pending rollout summaries into preferences.md, repository-facts.md, MEMORY.md, and memory_summary.md.

VT Code now treats LLM assistance as a hard requirement for memory mutation:

• natural-language remember and forget requests are planned through a structured LLM response
• session-finalization memory writes use the same LLM-assisted normalization path
• VT Code writes the files itself after validating the structured output
• if no memory LLM route is available, or the structured response is invalid, VT Code blocks the mutation and leaves memory unchanged

If agent.small_model.use_for_memory = true, VT Code prefers the configured lightweight-model route for memory planning, classification, cleanup, and summary refresh. Otherwise it uses the active session model/provider.

Interactive Controls

/memory

Use /memory as the memory-focused control surface.

• In inline UI, it shows loaded AGENTS.md sources, matched rules, memory status, file paths, and quick actions.
• Quick actions include toggling memory, toggling auto-write, toggling lightweight-memory routing, picking the memory triage model, scaffolding memory files, running one-time legacy cleanup, rebuilding the summary, opening the memory directory, and jumping to /config memory.
• In non-inline UI, /memory prints status plus exact follow-up commands such as /config memory and /edit <target>.
• /memory also shows whether cleanup is required because legacy raw prompts or serialized tool payloads were found in the memory store.

Natural-language memory prompts

VT Code also detects explicit memory-management prompts before they go to the model.

• Prompts like remember that I prefer pnpm, save to memory: use cargo nextest, and forget my pnpm preference open a human-in-the-loop confirmation dialog in inline UI.
• VT Code sends the raw request through the memory planner first, then shows the normalized fact or exact deletion candidates before applying the change.
• If the request is underspecified, such as save to memory and remember my name, VT Code asks for the missing detail before it writes anything.
• Prompts like show memory or what do you remember route to the existing /memory surface instead of sending the request to the model.
• If cleanup is required, VT Code asks you to run the one-time cleanup before any memory mutation.
• If inline selection UI is unavailable, VT Code does not mutate memory and points you back to /memory.

/config memory

Use /config memory to jump directly to the persistent-memory settings section. The same section is also reachable through /config agent.persistent_memory.

The focused controls cover:

• agent.persistent_memory.enabled
• agent.persistent_memory.auto_write
• agent.persistent_memory.startup_line_limit
• agent.persistent_memory.startup_byte_limit
• agent.persistent_memory.directory_override
• agent.instruction_import_max_depth
• agent.instruction_excludes
• agent.small_model.use_for_memory

directory_override is intentionally restricted to system, user, or project-profile config layers. A workspace-root vtcode.toml cannot redirect persistent memory storage.

For current-value fields such as startup line limits, byte limits, and import depth, pressing Enter on an empty inline input keeps the displayed value.

/init and Scaffolding

/init still generates the root AGENTS.md, and now also scaffolds:

• .vtcode/README.md
• the per-repository memory directory layout

Use /init --force when you want to regenerate the root guidance file and refresh workspace scaffolding in one pass.

Recommended Practices

• Keep authored guidance concise, reviewable, and intentionally human-written.
• Use .vtcode/rules/ for modular project rules instead of growing one large AGENTS.md.
• Reserve persistent memory for reusable learned facts, not policy or mandatory coding standards.
• Prefer /memory for day-to-day memory inspection and quick actions.
• Prefer /config memory when you need to tune limits, excludes, or the storage location.