Glossary
Vreko uses specific language to describe what it observes, learns, and predicts. These terms aren’t marketing — they’re the vocabulary the system uses internally, surfaced to you exactly as the service understands them.
A
AGENTS.md
The primary agent-facing intelligence document that Vreko writes into your workspace. It contains the compiled behavioral history of your codebase in a format AI tools can consume directly — fragile files, co-change relationships, known risk patterns, and session context. Every AI tool that reads this file starts with codebase knowledge it would otherwise have to discover through trial and error.
Updated automatically as the service’s intelligence state advances. See also: workspace.json, Intelligence State.
AI Attribution
The process of determining which AI tool made a given file modification — Cursor, Copilot, Claude Code, or a human direct edit. Attribution is tracked at 89% accuracy across the major AI coding tools and recorded in snapshot metadata, session history, and the fragility scoring pipeline.
Attribution powers downstream intelligence: a file that’s been repeatedly broken by a specific AI tool at a specific type of change is treated differently than one broken by varied causes.
AI Tool Drift Index
A compound signal that combines AI attribution confidence, fragility score, and blast radius into a single per-change risk metric: AI_confidence × fragility_score × log(blast_radius).
Where a single-dimension signal says “this file is fragile,” the drift index says “Cursor just modified a fragile file with 12 downstream dependents at high confidence.” It’s attribution plus consequence in one number, and it’s the signal most likely to surface in the fragility map and closing ceremonies.
B
Blast Radius
A measure of how many other files could break if a given file is modified incorrectly. Calculated using your dependency graph: direct importers, transitive dependents, cross-package references, and entry-point proximity — scaled logarithmically so the difference between 1 and 10 importers registers more than the difference between 100 and 110.
A file with a high blast radius isn’t necessarily fragile — it’s consequential. Combined with rollback history and AI attribution, it becomes part of the fragility score.
Scale: 0–100. Config files affecting the whole workspace can reach 95.
Bootstrap State
The first intelligence state. Vreko has been installed but hasn’t accumulated enough observations to generate reliable predictions. The system is actively watching and recording — it just hasn’t seen enough to calibrate.
During Bootstrap, Vreko uses a warm-start baseline derived from dogfood data to provide reasonable initial risk signals while your workspace-specific patterns accumulate. Bootstrap typically lasts until the first ~15–20 sessions.
C
Calibrating State
The second intelligence state. Vreko has accumulated enough observations to generate basic fragility scores, but patterns are still forming. Risk signals are descriptive rather than predictive — the system tells you what has happened, not what’s likely to happen next.
Transition: Bootstrap → Calibrating typically occurs after ~15 sessions.
Closing Ceremony
The structured review Vreko runs at the end of every development session. Not a report — a ritual. The ceremony:
- Summarizes all file modifications with AI tool attribution
- Identifies new patterns observed (co-changes, fragility signals, conventions)
- Evaluates which patterns should be promoted from session-level to permanent
- Calculates session coherence and estimated tokens saved
- Updates compiled context with new learnings
The ceremony is the moment where behavioral observation crystallizes into durable intelligence. It’s also the primary surface where you see the value delivered in a session — not what recovered, but what was learned and what was avoided.
Requires Pro tier or Pioneer access.
Co-Change Relationship
A learned association between two or more files that historically change together. If billing.ts and payment-processor.ts have been modified in the same session 14 out of 17 times, Vreko records this as a co-change pair.
Co-change relationships inform session coherence scoring (a session that modifies one without the other raises a flag), the fragility map visualization, and context compilation for AI tools. They represent behavioral coupling — not necessarily import coupling — which is why they surface patterns that static analysis misses.
Context Poisoning
Risk Pillar 05. A signal that tracks whether a file has become part of a self-referential AI modification loop — read as context by an AI tool, which then generates code that modifies the file, which is read as context again.
Files caught in this loop tend to drift in ways that are hard to trace because no single change looks catastrophic. The poisoning score captures chain depth × frequency. Higher values mean the file is in an increasingly circular AI-context relationship and should be reviewed carefully before further AI-assisted modification.
D
Service
The local background service (vrekod) that is the single source of truth for all Vreko intelligence. It watches your filesystem, manages sessions, runs the decision engine, maintains the knowledge store, and serves all surfaces — the VS Code extension, CLI, MCP server, and TUI — via JSON-RPC 2.0 over a Unix socket.
Code never leaves the service. The service never sends file content to the cloud. Metadata only, always.
Decision Engine
The three-layer system that determines when to create a snapshot and what scope it should cover:
Layer 1 — Deterministic (always runs, always free): Repo type detection, file classification, dependency graph, blast radius calculation. Budget: <50ms cached.
Layer 2 — Heuristic Scoring (always runs, always free): Seven weighted factors — category risk, blast radius, AI tool risk, change magnitude, session coherence, temporal risk, and critical path proximity — combined into a 0–100 risk score. Budget: <10ms.
Layer 3 — Personalization (Pro, async, non-blocking): User behavior history, aggregate cross-user patterns, Bayesian weight updates, rollback rate learning. Refines Layer 2 scores over time. Budget: <100ms, never blocks save handlers.
Score thresholds map to snapshot scope strategies: 0–30 creates a single-file snapshot, 30–50 includes direct dependents, 50–70 expands transitively, 70+ captures the full session scope.
E
Expert State
The fourth and final intelligence state. The service has accumulated enough observations across enough sessions that its predictions are reliably predictive rather than descriptive. Fragility scores reflect your specific codebase’s behavioral history, not just heuristics. Co-change relationships are validated by multiple observations. Risk weights have been personalized.
From Expert state forward, every session adds depth rather than breadth. The system doesn’t reset or restart — it compounds.
Also referred to internally as STEADY_STATE.
F
Fatigue
Risk Pillar 03. A signal that tracks whether the developer is reviewing AI suggestions carefully. Specifically: the rate at which AI tool suggestions are accepted within a short window, without apparent human modification. High fatigue scores indicate rapid, unreflective acceptance of AI output — a leading indicator of AI-induced regressions reaching production.
Fatigue is not a judgment about the developer. It’s a signal that the current session context warrants extra caution on any AI-assisted changes.
Fragile File
A file identified by the service as having a high probability of being broken by future modifications. Fragility is determined by the 6-pillar risk framework — combining rollback history, blast radius, AI attribution patterns, developer fatigue, context poisoning risk, and safe-to-write assessment.
A file becomes fragile through observed behavior, not static analysis. A file with no imports and a clean test suite can still be fragile if it’s been repeatedly rolled back after AI-assisted changes.
Fragility Map
The visual representation of your codebase’s fragile files and their co-change relationships. Rendered as a force-directed graph: node size encodes blast radius, node color encodes fragility score (gray → amber → rose), edge opacity encodes co-change frequency.
The fragility map makes behavioral coupling visible in a way that import graphs don’t — it shows the files that are dangerous together, not just the files that depend on each other.
Fragility Score
A continuous 0.0–2.5+ score produced by the unified risk provider that represents how likely a file is to cause problems if modified. The primary intelligence output of the service.
Unlike a 0–100 risk score (which is bounded and used for decision-making), the fragility score is unbounded — files that have been the source of repeated regressions, exhibit poisoning patterns, and have high blast radius can score above 2.0. This deliberate unboundedness makes extreme cases visible.
G
Git Risk
Risk Pillar 01. A multiplier applied to base risk scores based on the current state of your git repository. Inputs include: time since last commit, number of unstaged changes, whether you’re in a rebase or merge conflict state, and branch divergence from main. A session with 200 uncommitted lines on a rebasing branch multiplies every risk score in that session.
Git risk reads only .git metadata — never file content.
Ground Truth Skill
A set of structured workflows that read from Vreko’s intelligence documents (.vreko/docs/) to give AI agents factual grounding before beginning a task. The Ground Truth skill acts as the first step in any agent-assisted task: check what Vreko knows about the files you’re about to touch before touching them.
I
Intelligence State
The progression of Vreko’s predictive capability for a given workspace. States advance as observations accumulate — they never regress.
| State | Observations | What it means |
|---|---|---|
| Bootstrap | 0–~15 sessions | Watching and recording. Warm-start heuristics only. |
| Calibrating | ~15–40 sessions | Basic fragility scores. Descriptive, not predictive. |
| Aware | ~40–80 sessions | Reliable fragility scoring. Patterns are stabilizing. |
| Proficient | ~80–150 sessions | Predictive fragility. Co-change relationships validated. |
| Expert | 150+ sessions | Full intelligence. Predicts problems before they happen. |
Sub-workspaces in monorepos each maintain their own intelligence state. A workspace-level state provides the fallback for sub-workspaces that haven’t accumulated enough sessions individually.
Inter-Commit Space
The window of time and code change between git commits — the zone where AI tools do most of their work and where most AI-induced regressions originate. Git records commits; Vreko records everything that happens between them.
The inter-commit space is why Vreko exists. By the time a regression reaches a commit, the context of how it was introduced is already partially lost.
Invariant
A structural signature captured from a file when it’s identified as fragile. An invariant records the file’s key shape at the moment it was working correctly: exported symbols, critical function signatures, important import relationships.
Future modifications that deviate from the invariant signature generate an additional risk signal on top of the behavioral fragility score. Invariants combine structural intelligence (what working looks like) with behavioral intelligence (what breaks this file) — a Pro feature.
L
Learning
A durable pattern derived from observed session behavior. A learning is not a rule you configure — it’s something the service extracted from what actually happened in your codebase.
Learnings have a lifecycle: they begin as session-level observations, get promoted to workspace-level patterns when validated by multiple sessions, and can eventually become permanent calibration inputs for the decision engine. The closing ceremony is where promotion decisions are made.
Lineage ID
A tracing identifier attached to every prediction Vreko produces. A lineage ID traces a fragility score, risk assessment, or recommendation back to the specific observations and learnings that produced it — letting you verify why Vreko reached a conclusion rather than trusting a black box.
M
Momentum Score
An engagement metric that tracks how actively a workspace is building intelligence — session frequency, pattern promotion rate, recovery events, co-change discoveries. Momentum isn’t a quality score; it’s a velocity signal. High momentum means the intelligence flywheel is spinning.
Surfaced in the status bar tooltip and Pioneer dashboard.
O
Origin Label
A classification attached to every snapshot and session modification: INTERACTIVE (human-initiated change, keyboard input, manual edit) or AUTOMATED (AI tool action, MCP tool call, agent-generated modification). Origin labels are the foundation of AI attribution — every downstream intelligence signal traces back to this classification.
P
Pattern
A learned behavioral relationship that the service has extracted from observation. Patterns include co-change relationships, file fragility signals, AI tool accuracy profiles, and session coherence indicators. Unlike static analysis rules, patterns reflect what actually happens in your codebase — not what the structure implies should happen.
Patterns are session-scoped until promoted to permanent workspace learnings via the closing ceremony.
Pioneer
A member of Vreko’s early access program. Pioneers receive full Pro features free during the beta period in exchange for early feedback. Every Pioneer installation generates observations that advance the intelligence flywheel — which is why the program exists. More early users means more behavioral data, which means faster intelligence calibration for everyone.
Proficient State
The third intelligence state. Fragility scores are now predictive — the system has seen enough of your codebase’s behavioral history to anticipate problems, not just describe past ones. Co-change relationships are validated by multiple observations rather than inferred from single sessions.
Transition: Aware → Proficient typically occurs around 80 sessions.
Protection Decision
The composite output of the decision engine for a given save event. A protection decision is not just “create snapshot / don’t create snapshot” — it includes the scope strategy (single file, cluster, session-scope), the risk factors that drove the decision, and the snapshot metadata attached for future learning.
Protection decisions are the atomic unit through which Vreko learns: when a snapshot created on a protection decision is later rolled back, the system records a confirmed regression and updates its weights accordingly.
Pulse
The periodic intelligence summary delivered to your inbox. A Pulse is formatted like an instrument report — monospace, metrics-first, no marketing. It shows fragility trends, session activity, intelligence state transitions, and top fragile files for the period.
Pulses are only sent when there’s something to report. No activity, no email.
R
Risk Score
A bounded 0–100 composite score produced by Layer 2 of the decision engine for a given file or change event. Seven weighted factors combine into the score, which maps to a snapshot scope strategy. The risk score is the real-time decision signal; the fragility score is the accumulated behavioral signal. Both are distinct and complementary.
Rollback Patterns
Risk Pillar 02. Failure clusters derived from session history — files that are frequently rolled back together, specific change types that consistently precede recovery events, and AI tool and file type combinations with elevated rollback rates. The rollback patterns pillar converts recovery history into predictive signal: if a specific pattern has preceded a rollback 7 out of 10 times, the 11th occurrence of that pattern raises the risk score accordingly.
S
Safe-to-Write
Risk Pillar 06. A pre-write evaluation that runs before any MCP-mediated file modification. When an AI tool is about to write to a file, the service evaluates the current fragility score, session risk level, co-change cluster activity, and the agent’s historical trust score for that file category. The result is a safe-to-write signal — not a hard block, but an informed assessment that the agent can use to decide whether to proceed, snapshot first, or escalate.
Higher safe-to-write scores mean higher risk. The naming is intentional: it inverts the usual “higher = better” convention to force attention on files that need it.
Session
A bounded unit of development work, tracked from the first file modification to an explicit end event or an inactivity timeout. Sessions are the primary unit through which Vreko accumulates intelligence — everything learned is learned within the context of a session, and the closing ceremony runs at session end.
Sessions are workspace-aware: the service can track multiple concurrent sessions across multiple workspaces.
Session Coherence
A 0–100 score that measures whether the files touched in a session have a logical behavioral relationship to each other. Computed by comparing the session’s file set against known co-change relationships: a session that modifies auth.ts, token-store.ts, and session-middleware.ts (all known co-change partners) scores high. A session that modifies auth.ts, README.md, database-migrations.ts, and package.json (no historical co-change relationship) scores low.
Low coherence doesn’t mean the work is wrong — refactors legitimately touch unrelated files. It’s a signal that the session deserves extra attention, particularly if AI tools are driving the changes.
Snapshot
A point-in-time capture of file state, created intelligently by the decision engine rather than on a fixed timer. Snapshots are stored locally in content-addressable blob storage and never leave the machine. They carry metadata: risk score, origin label, AI attribution, session context, and the protection decision that triggered them.
Snapshots are the recovery mechanism. Intelligence is the prevention mechanism. The goal is for intelligence to make snapshots increasingly unnecessary.
T
Temporal Risk
One of the seven factors in Layer 2 heuristic scoring. Files modified infrequently over long periods are lower temporal risk. Files that are accumulating a high rate of change in a short window — especially in the current session — carry elevated temporal risk. Combined with blast radius and AI attribution, temporal risk captures the “moving fast in a dangerous place” scenario.
Trust Score
A per-agent, per-file-category metric that tracks how often an AI tool’s suggestions for a given type of file have been accepted, rolled back, or modified by a human before committing. A Cursor agent with a low trust score on authentication files will have its changes weighted more heavily in the safe-to-write evaluation and the AI tool drift index.
Trust scores accumulate over sessions and are workspace-specific. An agent that does excellent work on tests and poor work on config files will have differentiated trust scores across those categories.
W
workspace.json
The canonical structured intelligence file that Vreko generates for each workspace. It contains the full behavioral model of the workspace: fragility scores per file, co-change clusters, AI attribution history, session summary, intelligence state, and compiled patterns.
workspace.json is the machine-readable form of everything Vreko knows. AGENTS.md is the human-and-agent-readable summary derived from it. External tools, CI pipelines, and API consumers interact with workspace intelligence primarily through this file.
This glossary reflects terms as they exist in the current Vreko release. If you encounter a term in the product that isn’t defined here, let us know.