Veyra

Veyra — Engineering Intelligence for Coding Agents

Veyra is a plugin for DeepSeek Harness (DSH) that gives coding agents reliable, persistent, change-aware Engineering Memory — evidence-backed, project-isolated, and checked against the current repository — plus an optional structural code intelligence layer: the Dual-Brain architecture.

The Dual-Brain architecture

Veyra runs two complementary layers that answer different questions:

Brain	What it holds	Source of truth
Veyra Memory	Engineering lessons, root causes, decisions, constraints, and causal chains (`symptom → rootCause → remedy → verifiedOutcome`) — with evidence anchors, validation states, and authority levels	Epistemic state that accumulates across sessions
Code Intelligence	AST-level structural facts: symbols, files, call graphs, class hierarchies — always derived from the live repository	The repository itself, via `codebase-memory-mcp`

These are not the same thing. A Veyra memory record that says "the login function was refactored to use JWTs" is an engineering lesson; the call graph of login() today is structural truth. Code Intelligence can mark a memory potentially stale when files it references have changed — it never silently overwrites Veyra memory.

What Veyra does

Persistent engineering memory. Every record carries evidence anchors, a validation state (unverified → reviewed → verified), an authority level (candidate → derived → canonical), and causal facets. Your repository stays authoritative; Veyra never writes into it.
Hybrid search. One query, several signals: FTS5 BM25 + symbol/path boosts, token-level semantic overlap, intent affinity (why / how / what-changed), and relationship graph cohesion — with a transparent score breakdown. A goal argument steers ranking toward work you are pursuing (a direction, never an authority).
Code Intelligence. When codebase-memory-mcp is installed, seven agent tools give structural call-graph tracing, AST-level symbol search, file/component architecture summaries, and code-grounded search. When it is not installed, Veyra Memory runs normally without interruption.
Memory freshness and trust. Code Intelligence watches changed files, flags memories whose evidence anchors point to modified or deleted code, and applies retrieval penalties to stale records. At read time every recalled record is classified trusted / review_required / stale / contradicted / insufficient_evidence with reasons and an action — a projection only; it never writes, and never changes a record's authority or validation.
Change intelligence. Repository changes reach the agent context automatically — a change summary leads the recall block, with the trust impact of that recall — and veyra_change_impact analyzes an explicit set of changed files: affected memories, affected evidence anchors, optional review candidates, per-category summary counts. Candidates are never auto-promoted to canonical.
Health and maintenance. veyra_health and /veyra health report memory-health findings read-only; the bundled memory-maintenance skill applies lifecycle actions (keep / supersede / invalidate / forget / tombstone / revalidate / defer) only on explicit request, with safety limits and before/after reporting.
Human surfaces. /veyra slash commands, a read-only Knowledge Observatory, and an interactive Network Graph at /veyra in DSH Web.
Zero runtime npm dependencies. The package is pure ESM, ~180 kB packed.

Install
Quick Start
How memory works
Code Intelligence
Features
Commands
Tools
Skills
Memory rules
Configuration
Architecture
Troubleshooting
Development
Compatibility
License

Install

dsh plugin --profile web add @lovedolove/veyra

Restart DSH (or reload the profile) — Veyra activates automatically. No API keys, no external services, no configuration required to start using memory.

Quick Start

Do real work in DSH. Veyra observes session events automatically.
At end of turn, Veyra distills what happened into a candidate memory. Durable lessons become derived memory linked to neighbors.
Check what was stored:
```
/veyra recent
```
Ask for it back. In a later session in the same project, automatic recall injects the most relevant records into the turn — each marked not repository truth. Or search explicitly:
```
/veyra recall sqlite wal
```

Inspect, curate, and promote:

/veyra inspect vey_…           deep evidence, provenance, causal facets
/veyra forget vey_…            soft-forget (leaves recall, stays inspectable)
/veyra promote vey_… canonical only ever explicit, only ever on your word

See it as a graph. Open /veyra in the DSH Web address bar — a bounded workspace overview; /veyra?id=<record> centers the 1-hop Local Graph.
Unfamiliar repo? Load the bundled legacy-onboarding skill — it builds a Project Memory Baseline from evidence before your first change.

How memory works

Veyra observes session activity without touching your files.
End of a turn: Veyra distills the turn into a candidate — files, symbols, test outcomes, claim signal, and structured causal facets. Durable, grounded lessons become derived memory and are linked to neighbors (extended, updated, or contradicted). Near-duplicates are not cloned; repeated observations and verified outcomes strengthen existing records rather than adding new ones.
Automatic recall injects the top-N most relevant records into the agent's system-prompt context at the start of each turn, with a clear not repository truth notice.
Validation advances (unverified → reviewed → verified) as the same lesson is confirmed across sessions and test outcomes. Nothing becomes canonical without an explicit human instruction.

Code Intelligence

Code Intelligence is an optional structural layer powered by the external codebase-memory-mcp native daemon. Veyra does not bundle a native binary.

Install the native engine

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

The upstream installer places the binary in ~/.local/bin on Linux/macOS and %LOCALAPPDATA%\Programs\codebase-memory-mcp\ on Windows. See the upstream README for supported platforms and verification details.

Or set CBM_EXE=/path/to/codebase-memory-mcp to point to a pre-existing binary.

When the binary is absent

Code Intelligence enters degraded mode: all six cbm_* tools and veyra_code_status return a structured error with installation guidance. All Veyra Memory tools, Observatory, slash commands, and hybrid search continue working without any interruption.

What Code Intelligence provides

Tool	What it does
`cbm_projects`	List indexed projects
`cbm_search`	Find symbols, functions, classes, files by name/label
`cbm_snippet`	Retrieve exact symbol definition with line context
`cbm_trace`	Trace inbound/outbound call graph from a symbol
`cbm_arch`	Directory-level component dependency overview
`cbm_search_code`	Regex search over indexed repository files
`veyra_code_status`	Index status and memory freshness report

/veyra code commands

Command	What it does
`/veyra code status`	Index status and per-memory freshness (`FRESH / POTENTIALLY_STALE / INVALID`)
`/veyra code index`	Trigger repository reindexing
`/veyra code trace <symbol>`	Trace call graph for a symbol
`/veyra code impact`	Check which memories reference recently changed code

Code truth vs. Veyra memory

The distinction matters:

Code Intelligence reports structural facts from the live AST: who calls login(), what AuthService exposes. These are authoritative for the current state of the repository.
Veyra Memory records engineering knowledge: why login() was changed, what the failure mode was, what the constraint is for future callers. These persist across refactors — and Code Intelligence will flag them as potentially stale when the referenced file changes, so you know to verify them.

Neither brain replaces the other.

Features

Feature	Description
Ambient memory loop	Observes session events, distills turns into candidates, learns durable lessons, strengthens repeats, marks drifted knowledge stale.
Hybrid Search	FTS5 BM25 + symbol/path boosts, token-level semantic overlap, intent affinity, relationship graph cohesion — with a transparent score breakdown.
Unified RAG	`kind: 'knowledge'` records hold project documentation next to engineering memory; both are searched together.
Causal knowledge	Structured `symptom → rootCause → remedy → verifiedOutcome` facets, contradiction detection, and side-by-side conflict views.
Code freshness	Evidence anchors track files and symbols; changed or deleted files mark memory `POTENTIALLY_STALE` or `INVALID` and apply retrieval penalties.
Change intelligence	Repository watcher changes reach ambient context automatically (change summary + trust impact); `veyra_change_impact` maps changed files to affected memories, affected anchors, and optional review candidates.
Trusted context	Every recalled record is classified `trusted / review_required / stale / contradicted / insufficient_evidence` with reasons and an action — a read-time projection that never writes or changes authority/validation.
Memory health	`veyra_health` / `/veyra health` findings (read-only), plus the `memory-maintenance` skill that applies lifecycle actions on explicit request only.
Knowledge Observatory	Read-only text dashboard: overview, search signals, record inspection, causality, relationships, contradictions, and consolidation proposals.
Network Graph	Host-native SVG page at `/veyra` (overview + 1-hop Local Graph), served by the DSH web server; JSON at `/veyra/graph`, `/veyra/record`, `/veyra/search`.
Settings	`Recall limit` and `Include reusable` in the DSH Settings dialog (Veyra section); changes apply from the next turn, no restart.
Project isolation	Memory is keyed by workspace path + git remote. Two unrelated folders never share memory; `scope: 'reusable'` is opt-in.
Secret redaction	Secrets are redacted before anything is stored.

Commands

Command	What it does
`/veyra`	Status and memory counts for this workspace
`/veyra observatory`	Knowledge Observatory overview
`/veyra observatory search <query>`	Inspect hybrid search signals and score breakdowns
`/veyra observatory record <id>`	Deep inspection (What, Why, Where, When, Evidence, Validation)
`/veyra observatory causality`	Causal knowledge map
`/veyra observatory relationships [id]`	Directed graph projection of knowledge links
`/veyra observatory local <id>`	1-hop Local Graph around a record
`/veyra observatory contradictions`	Active conflicting claims side-by-side
`/veyra observatory consolidation`	Consolidation candidates — read-only, never changes records
`/veyra recall [query]`	Hybrid search project (+ reusable) memory
`/veyra recent`	Recent records, including candidates
`/veyra inspect <id>`	Read one record with deep provenance and causal facets
`/veyra forget <id>`	Soft-forget
`/veyra invalidate <id> [reason]`	Mark invalid; reason kept in lifecycle history
`/veyra supersede <id> <replacementId> [why]`	Retire a record in favour of a replacement
`/veyra tombstone <id> [override] [reason]`	Retire to historical (still inspectable)
`/veyra protect <id> [reason]` / `/veyra unprotect <id>`	Guard a memory against forgetting (auditable)
`/veyra promote <id> [derived\|canonical]`	Change standing — canonical only on explicit user request
`/veyra health [threshold]`	Memory-health findings — read-only, never mutates records
`/veyra code status`	Code Intelligence index status and memory freshness
`/veyra code index`	Trigger repository reindexing
`/veyra code trace <symbol>`	Trace call graph for a symbol
`/veyra code impact`	Check memories affected by changed code
Network Graph	`/veyra` in DSH Web; `/veyra?id=<record>` centers the 1-hop view

Tools

Memory tools (always available): veyra_remember, veyra_recall, veyra_inspect, veyra_forget, veyra_promote, veyra_feedback, veyra_recurrence, veyra_health

Change intelligence (always available; degrades to path matching without the binary): veyra_change_impact

Code Intelligence tools (require codebase-memory-mcp binary; degrade gracefully when absent): cbm_projects, cbm_search, cbm_snippet, cbm_trace, cbm_arch, cbm_search_code, veyra_code_status

Load the bundled veyra skill for full guidance on when to call each tool and how they interact.

Skills

Five skills ship inside the package and register automatically (no separate install):

Skill	Use it when
`veyra`	You need Veyra's own guidance: tool usage, candidate/derived/canonical, causal facets, hybrid search semantics, and the rule that repo truth wins.
`codebase-memory`	You are using Code Intelligence tools (`cbm_*`): when to prefer `cbm_trace` vs. grep, how to navigate from a symbol to its call graph, and how Code Intelligence and Veyra Memory complement each other.
`legacy-onboarding`	First entry into an unfamiliar or legacy repo: baseline assessment, progressive investigation depth, evidence-first extraction, and building a Project Memory Baseline.
`memory-review`	You want to audit this conversation for durable engineering memory: what is already recorded, what is missing, what looks stale or conflicting.
`memory-maintenance`	You explicitly ask to clean up or maintain memory: runs the health findings and lifecycle actions (keep / supersede / invalidate / forget / tombstone / revalidate / defer) with before/after reporting — health findings alone are never authorization.

Memory rules

What	Authority	Auto-recalled?
Auto-captured observation	`candidate`	no
Remembered / learned lesson	`derived`	yes
Explicitly promoted truth	`canonical`	yes

Canonical is never assigned automatically. Repository files stay authoritative — Veyra never writes into your repo. Similarity is not identity: overlapping memories are linked, not merged. Secrets are redacted. Projects are isolated; reusable memory is opt-in.

Configuration

DSH Settings exposes Recall limit and Include reusable under a dedicated Veyra section. A saved change applies from the next turn, no restart.

recallLimit: 0 disables automatic recall context only — tools, /veyra, Observatory, and stored memory all stay available.

Everything else is configured in the profile cordis.patch.yml:

- id: veyra
  name: '@lovedolove/veyra'
  config:
    recallLimit: 5       # 0 = no automatic recall context (also settable in Settings)
    includeReusable: true
    observe: true        # capture session activity
    learn: true          # promote durable observations
    codebaseWatch: true  # watch repo for file changes to flag stale memories
    home: "~/.dsh/veyra" # storage root (yaml-only)

observe / learn / home / codebaseWatch are yaml-only. VEYRA_HOME overrides the storage root from the environment.

Architecture

  DSH host — Cordis plugin (src/plugin.mjs)
  session events ──► observe ──► candidate ──► learn ──► derived memory
                                                      │
  ┌──────────────────────────────────────────────────────────────────────────┐
  │  SQLite store  ~/.dsh/veyra/  (node:sqlite + FTS5, one DB per project)  │
  └──────────────────────────────────────────────────────────────────────────┘
        projections (read-only)
  ┌───────────────┬────────────────┬─────────────────┬────────────────────────┐
  ▼               ▼                ▼                 ▼
  Hybrid Search   Local Graph      Agent context     Human surfaces
  recall/tools    (1-hop, bounded) systemPrompt      /veyra commands
  observatory     src/graph.mjs    (fail-closed)     Observatory / Network Graph

  ┌──────────────────────────────────────────────────────────────────────────┐
  │  Code Intelligence  src/code/  (optional — requires codebase-memory-mcp)│
  │                                                                          │
  │  stdio JSON-RPC 2.0 ──► cbm_* tools ──► freshness checks ──► retrieval  │
  │  client.mjs  engine.mjs  discovery.mjs  linking.mjs  watcher.mjs        │
  │                                                                          │
  │  Degraded when binary absent: memory layer unaffected                   │
  └──────────────────────────────────────────────────────────────────────────┘

The local graph is a derived projection, not a second store. Code Intelligence is an optional layer communicating with an external native daemon over stdio; it never modifies Veyra Memory directly.

Full write-up: docs/architecture-graph.md

Troubleshooting

No [veyra] lines at boot. The plugin was installed into a different profile than the one you booted. dsh plugin --profile web add … installs into web; booting dsh tui will not have it. Also check Settings → Plugins.

Node is too old. Veyra requires Node ≥ 22.5 and < 25 (engines.node). It uses node:sqlite, which first shipped in Node 22.5. Upgrade Node, then reinstall.

"Plugin … is incompatible with dsh …" The package's compatibility range is >=0.1.2-rc.1 <0.3.0-0. Update DSH, or accept the risk with the exact-version exemption DSH prints.

Automatic recall context is empty. Check: (1) recallLimit is not 0 — Settings → Veyra; (2) records you expect are not still candidate (candidates are never auto-recalled); (3) you are in the same project — run /veyra and confirm the workspace path and project id.

Code Intelligence shows "degraded". The codebase-memory-mcp binary is not on your PATH and CBM_EXE is not set. Install via the curl command above or set CBM_EXE=/path/to/binary. All Veyra Memory tools continue working.

/veyra code status reports stale memories. The referenced files changed since the memory was recorded. Verify the memory against the current repo (/veyra inspect <id>), update it with veyra_remember, or forget it if it no longer applies.

The Network Graph page looks empty. Either the workspace has no records yet (/veyra recent), or the page resolves a different workspace — /veyra prints the workspace path it uses.

Where is my data / how do I reset. $DSH_HOME/veyra/ (default ~/.dsh/veyra/), or $VEYRA_HOME if set. Delete a project's store to start over; nothing is stored in your repository.

Something wrote wrong memory. /veyra forget <id> soft-forgets (inspectable, out of recall). Nothing becomes canonical without you running /veyra promote <id> canonical.

Development

npm test               # node --test test/*.test.mjs  (755 tests)
npm run pack:check     # npm pack --dry-run — what would be published

CI runs both on Node 22 and 24 for every push and pull request. Publishing is automatic: every push to main publishes to npm (patch-bumped first if the version already exists) unless the commit message contains [skip publish]. Every published version gets a matching GitHub Release tagged vX.Y.Z.

Compatibility


Current release	`0.1.51`
Node	`>=22.5.0 <25.0.0`
DSH	`>=0.1.2-rc.1 <0.3.0-0`
Verified on	DSH `0.1.7-rc.2` (plugin boot, tools, `/veyra` + `/veyra/graph`); DSH `0.2.0-rc.1` (real compatibility gate + composed-host-service runtime); DSH `0.2.0-rc.2` (composed host-service runtime + real `ToolRuntime` tool-output validation against the declared range); CI on Node 22 and 24
Profiles	Installed per profile (`web`, `tui`, …); Settings section and Network Graph require the web surface
Storage	`node:sqlite` + FTS5, one DB per project under the Veyra home
Code Intelligence	Optional; requires external `codebase-memory-mcp` binary (MIT, DeusData)
License	MIT

Veyra is on a pre-1.0 0.1.x line — see the CHANGELOG for what shipped. APIs and command surface may still change between minor versions.

License

MIT — see LICENSE.

Third-party attributions — see THIRD_PARTY.md.

veyra

Cài đặt

Mã nguồn

Thẻ

Readme