Veil帳

A session with no memory relearns the codebase every time it starts. It rediscovers a constraint you explained last week. It retries a fix that already failed.

Compaction does not fix this. The summariser keeps whatever looks important by a fixed heuristic and drops the rest, and the dropped part matters more often than the tool assumes.

Veil replaces that summariser with an eviction system. Every piece of context carries its own decay schedule, so no single pass wipes a session.

The published package is @engrammic/veil. It installs globally and replaces the agent binary inside a project directory.

npm install -g @engrammic/veil
cd your-project
veil

Embeddings run through sqlite-vec, with the embedder in-process and Ollama as a fallback, so the store works with the network off.

Veil is a fork of pi-mono, Mario Zechner’s agent harness, not a plugin on top of one. The memory layer runs inside the loop: a manifest of what is currently loaded gets appended to the system prompt, and every tool call passes through capture, scoring and eviction on the way in and out.

const harness = new VeilHarness({ dbPath: '.veil/context.db' })
const config: AgentLoopConfig = {
  ...baseConfig,
  ...harness.getHooks(),
}

The model can also call the memory layer directly. Twelve tools are registered for it.

Most cache eviction runs a plain age check: old enough, gone. Veil scores memory with FSRS instead, the scheduler behind spaced-repetition flashcard apps. Each item holds a stability in days, and retrievability falls from it on a power curve, calibrated so an item is still at 0.9 when it reaches its own stability.

Recall raises stability, and the increment grows as retrievability falls, so an item recalled late gains more than one recalled constantly. The same curve runs twice at different horizons: stability caps at seven days in the live context window and at a year in the durable store.

Deciding what a piece of context is worth never calls the LLM. Five metadata signals combine at fixed weights, and the whole thing is arithmetic.

Recency is FSRS retrievability. Frequency is a log-scaled access count. Relevance is Jaccard overlap between the item’s tags and the current task. Structure asks whether the item points into the code graph. Cognitive weight tracks whether the item was in context when things went well or badly. Procedural items then get a 1.2 multiplier, anything you loaded by hand gets 1.5, and pinned items take a flat boost.

The same inputs produce the same score on every turn.

Eviction runs in three stages, and each one has a real predicate rather than a budget someone guessed.

The threshold that decides what counts as low enough moves on its own, borrowing the AIMD shape from TCP congestion control. Nobody sets an eviction budget by hand; the threshold finds its own level from how the session is going.

Turns get the same treatment as context items. The last twelve are protected outright. Older ones score by what kind of turn they were, and a turn the current one still refers to gets rescued: cosine similarity above 0.7 against a recent turn cuts its eviction score.

Corrections and intent carry a weight of zero, so they never become eviction candidates.

Veil keeps a record of every attempt against a goal: what the agent did, the target, the outcome, and a normalised fingerprint of the error. That fingerprint lets the same failure get recognised as the same failure even when the message text drifts.

A convergence monitor watches the record and escalates in levels. Progress counts as a pass, a partial, a different error pattern, or a different file touched. Anything else is the agent going in circles.

Evicted context is demoted, not dropped. It moves out of the prompt into the warm cache at .veil/context.db, and out of there into cold storage, which hands back a pointer the agent can follow. The durable store underneath is an event log: the tape is the truth and everything else is derived from it.

Contradictions are not resolved quietly. Two beliefs that disagree are stored with their full provenance, down to the tool call and the session that produced them, and handed to the model to settle.

Eviction is not silent in the interface. When context leaves the window, the tool calls it came from are dimmed in the transcript, so the record of what the agent no longer knows stays on screen.