Memory
By default, each session starts fresh: Veyyon holds no record of your last one. Turn memory on and it
carries durable project context forward, so a fact it learned yesterday is available today. Memory is
off by default. To use it, you pick a backend, which is the store that holds what Veyyon remembers, in
config.yml or /settings.
Backends
| Backend | Storage | Notes |
|---|---|---|
off | n/a | No memory injection or retention |
local | Markdown under the agent memories dir (MEMORY.md, memory_summary.md, skills/) | Summaries from past session files |
mnemopi | SQLite via @veyyon/mnemopi | Vector + FTS, auto-retain, compaction hooks |
hindsight | Hindsight server (when configured) | Remote bank; retain/recall/reflect tools |
Enable in config:
memory:
backend: mnemopi # or local, hindsight, off
Mnemopi (recommended for long-running work)
With memory.backend: mnemopi, Veyyon:
- Opens scoped SQLite banks (
global,per-project, orper-project-tagged). - Recalls relevant memories into a
<memories>block on the first turn, delivered as a message next to your prompt rather than by rewriting the cached system prompt. - Retains completed turns on a configurable interval (
mnemopi.retainEveryNTurns, default 4). - Supplies pre-compaction context from the memory backend when compaction runs.
Key settings: mnemopi.scoping, mnemopi.recallLimit, mnemopi.autoRecall, mnemopi.autoRetain,
mnemopi.polyphonicRecall, mnemopi.noEmbeddings. See
docs/internal/mnemosyne-memory-backend.md.
Dedicated tools when enabled: recall, retain, reflect, memory_edit.
The /memory slash command exposes view, stats, diagnose, clear, and enqueue.
Local summary pipeline
With memory.backend: local, a background pipeline at startup extracts durable signal from past
session JSONL files, then consolidates into MEMORY.md, memory_summary.md, and optional
skills/. The agent reads artifacts via memory:// URLs on the read tool.
Engineering detail: docs/handbook/src/architecture/memory.md.
Compaction (primary knobs)
Context compaction is separate from durable memory. Settings → Compaction (or config.yml) exposes
these primary fields:
| Setting | Key | Values |
|---|---|---|
| Threshold | compaction.threshold | auto, a percent of the window (85%), or a token amount (170000) |
| Type | compaction.strategy | summary, the sole strategy |
| Model | compaction.model | model id; unset uses the interactive model |
summary rewrites old history into an in-place LLM summary. Run it on demand
with /compact. Use /handoff only when you explicitly want a new session. See
Compaction and project memory.
What the model sees
Recalled or summarized memory is background context, not instructions. Current user messages, tool output, and repo state win on conflict. The agent should cite memory paths when memory changes a plan and pair citations with fresh repo evidence.
It arrives in two places. The guidance that stays the same all session is part of the system prompt. Anything that changes while you work, the memories recalled for your current question and the mental models when they reload, arrives as a message next to your prompt instead.
That split is about cost, not ordering. The provider caches the system prompt as the prefix of every request; changing it mid-session throws that cache away and the next request re-reads the whole conversation at the uncached rate. A recalled memory in the prompt made every recall cost a full re-read. The model reads the same text either way.
A block is sent once. A reload that finds the same memories sends nothing, so your context does not
grow by a copy of your memories every turn. /memory view shows both halves, so what you read there
is what the model gets.
Configuration
Use /memory or /settings (Memory group), or set keys under memory.*, mnemopi.*,
hindsight.*, or memories.* depending on the active backend.
The active backend, its settings, and its stored data (mnemopi SQLite path, local Markdown artifacts, hindsight bank id) are scoped to the active profile (VEYYON_PROFILE). Profiles do not share memory stores.