Project Memory: Preserve Constraints Worth Keeping
The Engineer's Dilemma: Build conventions, test prerequisites, and environment troubleshooting tricks often get trapped in individual heads or scattered across countless chat sessions. Engineers must re-explain rules every time they start a session. Worse, when build rules evolve, obsolete memories linger as invisible interference, hard to trace or decommission.
01
Extract from Messages or Manually Propose Candidate
Extract verified engineering facts (e.g., "run python3 scripts/check-repository.py before commit") directly from recorded session evidence, or draft a memory proposal manually. All initial entries default to
Candidate state, preserving source session IDs and extraction timestamps.
02
Verify Source & Assign Engineering Scope
Every memory is assigned to an explicit scope (such as
test-practices, build-system, or workspace-rules). The Private Library is maintained in strict isolation and never exposed to project memory streams or prompt retrieval contexts.
03
Human Review & State Activation (Active)
Adheres to the principle that "stored does not mean active for models." Engineers inspect and refine the recorded facts before manually promoting the entry to
Active. Unaudited candidates never enter context retrieval.
04
Scoped Retrieval & Explicit Superseding (Supersede / Archive)
Perform pure local lexical retrieval within a controlled token budget via MCP tools or CLI. When project conventions evolve, explicitly designate new memories to supersede old ones (
Superseded) or archive them entirely (Archived), preventing outdated rules from polluting prompts.
macOS native preview interface (0.1.0-preview.2) · Synthetic data
Boundaries & Known Limitations
- Lexical & Scope Indexing: Vela uses pure local SQLite for scope, keyword, and lexical matching, with zero reliance on remote vector databases, embedding APIs, or external cloud persistence.
- Model Adherence Requires Independent Evidence: Retrieving Active memories within budget and injecting them into context does not guarantee that downstream coding agents will comprehend and strictly follow them. Adherence depends on task complexity and the harness itself.
- Strict Isolation for Private Library: The Private Library is reserved exclusively for personal sensitive notes and local private reference. It is strictly segregated from project memories and never exposed to agent retrieval protocols or model prompts.