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.

A conversation summary can omit a detail that becomes useful later. I wanted a way to retain and retrieve individual records as the active context changes.

Veil scores context items and moves them between the active prompt and local storage. Eviction frees space in the prompt while keeping records available for retrieval.

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

The memory store uses sqlite-vec, with an in-process embedder and Ollama as a fallback. Model files need to be available locally for offline embedding. The coding agent's model provider is configured separately; choosing a remote model can send context to that provider.

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.

Veil uses an FSRS-based retrievability score, adapted from spaced-repetition scheduling. 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.

The scorer combines five metadata signals at fixed weights. It does not call a language model.

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 metadata, task tags, and time produce the same score.

Eviction runs in three stages, using age, scores, and context pressure to choose candidates.

The controller adjusts the context-pressure threshold within configured limits. It responds to repeated evictions, requests for evicted items, and periods of stability.

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 records attempts 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. These are heuristics for deciding when to intervene.

Evicted context 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. An event log records changes in the durable store, and the current view is derived from that log.

Conflicting beliefs are stored with their 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.