total-recall-brain 3.3.0 → 3.5.0

package/frontend/src/pages/SettingsPage.tsx

@@ -35,6 +35,7 @@ export default function SettingsPage() {
       if (!data.budget.budget) data.budget.budget = { daily_cap_usd: 5.0, weekly_cap_usd: 25.0, enabled: true };
       if (!data.brain) data.brain = {};
       if (!data.brain.preferred_agent) data.brain.preferred_agent = 'auto';
+      if (!data.secrets) data.secrets = {};
       
       setConfigData(data);
     } catch (err: unknown) {
@@ -152,6 +153,17 @@ export default function SettingsPage() {
     });
   };
 
+  const updateSecretsProp = (prop: string, value: string) => {
+    if (!configData) return;
+    setConfigData({
+      ...configData,
+      secrets: {
+        ...configData.secrets,
+        [prop]: value
+      }
+    });
+  };
+
   return (
     <div className="page" style={{ display: 'flex', flexDirection: 'column', height: '100%' }}>
       <div className="page-header" style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', flexWrap: 'wrap', gap: 16 }}>
@@ -209,7 +221,7 @@ export default function SettingsPage() {
         </div>
       ) : viewMode === 'visual' && configData ? (
         /* ==================== VISUAL CONTROL PANEL UI ==================== */
-        <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(360px, 1fr))', gap: 24, flex: 1, minHeight: 0, overflowY: 'auto', paddingBottom: 24 }}>
+        <form onSubmit={(e) => { e.preventDefault(); handleSaveVisual(); }} style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(360px, 1fr))', gap: 24, flex: 1, minHeight: 0, overflowY: 'auto', paddingBottom: 24 }}>
           
           {/* Card 1: AI Reasoning & Autonomy */}
           <div className="card" style={{ padding: 24, display: 'flex', flexDirection: 'column', gap: 20, background: 'rgba(18, 18, 26, 0.6)', backdropFilter: 'blur(8px)', border: '1px solid var(--border)' }}>
@@ -537,7 +549,190 @@ export default function SettingsPage() {
             </div>
           </div>
 
-        </div>
+          {/* Card 5: API Keys & Integrations */}
+          <div className="card" style={{ padding: 24, display: 'flex', flexDirection: 'column', gap: 20, background: 'rgba(18, 18, 26, 0.6)', backdropFilter: 'blur(8px)', border: '1px solid var(--border)' }}>
+            <div style={{ display: 'flex', alignItems: 'center', gap: 10, borderBottom: '1px solid var(--border)', paddingBottom: 12 }}>
+              <span style={{ fontSize: 20 }}>🔑</span>
+              <div>
+                <h3 style={{ fontSize: 15, fontWeight: 600 }}>API Keys & Integrations</h3>
+                <p style={{ fontSize: 11, color: 'var(--text-tertiary)' }}>Manage access keys and tokens for AI models and search providers</p>
+              </div>
+            </div>
+
+            {/* Google Gemini API Key */}
+            <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+              <label htmlFor="google_api_key" style={{ fontSize: 13, fontWeight: 500 }}>Google Gemini API Key</label>
+              <input
+                id="google_api_key"
+                type="password"
+                placeholder="AIzaSy..."
+                value={configData.secrets?.google_api_key || ''}
+                onChange={(e) => updateSecretsProp('google_api_key', e.target.value)}
+                style={{
+                  background: 'var(--bg-tertiary)',
+                  color: 'var(--text-primary)',
+                  border: '1px solid var(--border)',
+                  padding: '8px 12px',
+                  borderRadius: 6,
+                  outline: 'none',
+                  fontSize: 13
+                }}
+              />
+            </div>
+
+            {/* Anthropic API Key */}
+            <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+              <label htmlFor="anthropic_api_key" style={{ fontSize: 13, fontWeight: 500 }}>Anthropic API Key (Claude Code)</label>
+              <input
+                id="anthropic_api_key"
+                type="password"
+                placeholder="sk-ant-..."
+                value={configData.secrets?.anthropic_api_key || ''}
+                onChange={(e) => updateSecretsProp('anthropic_api_key', e.target.value)}
+                style={{
+                  background: 'var(--bg-tertiary)',
+                  color: 'var(--text-primary)',
+                  border: '1px solid var(--border)',
+                  padding: '8px 12px',
+                  borderRadius: 6,
+                  outline: 'none',
+                  fontSize: 13
+                }}
+              />
+              <span style={{ fontSize: 10, color: 'var(--text-tertiary)' }}>Configuring this allows Claude Code CLI to run without prompting for OAuth login.</span>
+            </div>
+
+            {/* OpenAI API Key */}
+            <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+              <label htmlFor="openai_api_key" style={{ fontSize: 13, fontWeight: 500 }}>OpenAI API Key (Codex)</label>
+              <input
+                id="openai_api_key"
+                type="password"
+                placeholder="sk-proj-..."
+                value={configData.secrets?.openai_api_key || ''}
+                onChange={(e) => updateSecretsProp('openai_api_key', e.target.value)}
+                style={{
+                  background: 'var(--bg-tertiary)',
+                  color: 'var(--text-primary)',
+                  border: '1px solid var(--border)',
+                  padding: '8px 12px',
+                  borderRadius: 6,
+                  outline: 'none',
+                  fontSize: 13
+                }}
+              />
+            </div>
+
+            {/* Tavily API Key */}
+            <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+              <label htmlFor="tavily_api_key" style={{ fontSize: 13, fontWeight: 500 }}>Tavily Search API Key</label>
+              <input
+                id="tavily_api_key"
+                type="password"
+                placeholder="tvly-..."
+                value={configData.secrets?.tavily_api_key || ''}
+                onChange={(e) => updateSecretsProp('tavily_api_key', e.target.value)}
+                style={{
+                  background: 'var(--bg-tertiary)',
+                  color: 'var(--text-primary)',
+                  border: '1px solid var(--border)',
+                  padding: '8px 12px',
+                  borderRadius: 6,
+                  outline: 'none',
+                  fontSize: 13
+                }}
+              />
+            </div>
+
+            {/* Other Search Keys (Brave, Exa, Serper) */}
+            <details style={{ fontSize: 13, color: 'var(--text-secondary)' }}>
+              <summary style={{ cursor: 'pointer', fontWeight: 500, outline: 'none', padding: '4px 0' }}>More Provider Keys (Brave, Exa, Serper, GitHub)</summary>
+              <div style={{ display: 'flex', flexDirection: 'column', gap: 16, marginTop: 12, paddingLeft: 8, borderLeft: '2px solid var(--border)' }}>
+                {/* Brave Search Key */}
+                <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+                  <label htmlFor="brave_api_key" style={{ fontSize: 12, fontWeight: 500 }}>Brave Search API Key</label>
+                  <input
+                    id="brave_api_key"
+                    type="password"
+                    value={configData.secrets?.brave_api_key || ''}
+                    onChange={(e) => updateSecretsProp('brave_api_key', e.target.value)}
+                    style={{
+                      background: 'var(--bg-tertiary)',
+                      color: 'var(--text-primary)',
+                      border: '1px solid var(--border)',
+                      padding: '8px 12px',
+                      borderRadius: 6,
+                      outline: 'none',
+                      fontSize: 13
+                    }}
+                  />
+                </div>
+
+                {/* Exa Search Key */}
+                <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+                  <label htmlFor="exa_api_key" style={{ fontSize: 12, fontWeight: 500 }}>Exa API Key</label>
+                  <input
+                    id="exa_api_key"
+                    type="password"
+                    value={configData.secrets?.exa_api_key || ''}
+                    onChange={(e) => updateSecretsProp('exa_api_key', e.target.value)}
+                    style={{
+                      background: 'var(--bg-tertiary)',
+                      color: 'var(--text-primary)',
+                      border: '1px solid var(--border)',
+                      padding: '8px 12px',
+                      borderRadius: 6,
+                      outline: 'none',
+                      fontSize: 13
+                    }}
+                  />
+                </div>
+
+                {/* Serper API Key */}
+                <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+                  <label htmlFor="serper_api_key" style={{ fontSize: 12, fontWeight: 500 }}>Serper (Google Search API) Key</label>
+                  <input
+                    id="serper_api_key"
+                    type="password"
+                    value={configData.secrets?.serper_api_key || ''}
+                    onChange={(e) => updateSecretsProp('serper_api_key', e.target.value)}
+                    style={{
+                      background: 'var(--bg-tertiary)',
+                      color: 'var(--text-primary)',
+                      border: '1px solid var(--border)',
+                      padding: '8px 12px',
+                      borderRadius: 6,
+                      outline: 'none',
+                      fontSize: 13
+                    }}
+                  />
+                </div>
+
+                {/* GitHub Token */}
+                <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+                  <label htmlFor="github_token" style={{ fontSize: 12, fontWeight: 500 }}>GitHub Personal Access Token</label>
+                  <input
+                    id="github_token"
+                    type="password"
+                    placeholder="ghp_..."
+                    value={configData.secrets?.github_token || ''}
+                    onChange={(e) => updateSecretsProp('github_token', e.target.value)}
+                    style={{
+                      background: 'var(--bg-tertiary)',
+                      color: 'var(--text-primary)',
+                      border: '1px solid var(--border)',
+                      padding: '8px 12px',
+                      borderRadius: 6,
+                      outline: 'none',
+                      fontSize: 13
+                    }}
+                  />
+                </div>
+              </div>
+            </details>
+          </div>
+
+        </form>
       ) : (
         /* ==================== RAW YAML EDITOR UI ==================== */
         <div style={{ display: 'flex', flexDirection: 'column', flex: 1, minHeight: 0 }}>

package/frontend/src/types.ts

@@ -159,5 +159,21 @@ export interface ConfigJson {
   brain?: {
     preferred_agent?: string
   }
+  secrets?: {
+    google_api_key?: string
+    anthropic_api_key?: string
+    openai_api_key?: string
+    tavily_api_key?: string
+    brave_api_key?: string
+    exa_api_key?: string
+    serper_api_key?: string
+    github_token?: string
+  }
+}
+
+export interface UpdateCheckResult {
+  currentVersion: string
+  latestVersion: string
+  updateAvailable: boolean
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "Sovereign AI system — database-free, SSSS-powered personal intelligence engine deployable to any POSIX host.",
   "type": "module",
   "bin": {
@@ -50,7 +50,7 @@
     "local-llm"
   ],
   "author": "gregiteen",
-  "license": "ISC",
+  "license": "MIT",
   "bugs": {
     "url": "https://github.com/gregiteen/total-recall/issues"
   },

package/scaffold/.agent/skills/total-recall/SKILL.md

@@ -26,9 +26,10 @@ You MUST actively reference and apply this skill under the following specific ru
 
 ### 3. When searching for complex domain knowledge or general facts
 *   **Trigger**: When you need to retrieve deep factual information (e.g. from the `facts/` category) or conceptual domain structures (e.g. from `concepts/`) that are not present in your active instruction files.
-*   **Action**: Use the two complementary search modes:
-     *   **Regular Text Search** (e.g. filesystem grep / literal matching): Use this when searching for specific literal keywords, exact config keys, exact filenames, or exact slugs.
-     *   **Semantic Search (REST API POST `/api/memory/search/semantic`)**: Use this when searching for conceptual matching, high-level intent, design patterns, or user preferences. Do NOT rely on only one search mode; combine both to ensure absolute coverage.
+*   **Action**: Use the semantic/lexical hybrid search engine (via the local `recall` command, or `/api/memory/search/semantic` endpoint) along with regular text search (e.g., grep):
+     *   **Hybrid Search**: Blends cosine-similarity vector search and lexical density TF-IDF keyword matching using Reciprocal Rank Fusion (RRF). This blends intent-based semantic matching with exact keyword accuracy.
+     *   **Hierarchical Parent-Child Search**: Memory node bodies are chunked and indexed as children. The vector store searches both the parent node and child chunks, returning matches based on maximum similarity.
+     *   **Regular Text Search**: Use grep to locate exact configurations, literal keys, or symbols.
 
 ### 4. When a topic requires deep, structured domain learning and mastery
 *   **Trigger**: When you encounter a complex architectural topic, a deep conceptual system, or a technical domain where you need to acquire deep mastery to proceed effectively.
@@ -37,7 +38,7 @@ You MUST actively reference and apply this skill under the following specific ru
 
 ### 5. When you modify, add, or delete files in the memory vault
 *   **Trigger**: Immediately after performing any memory node writes.
-*   **Action**: Rebuild the instruction shims by sending a POST request to `/api/vault/compile`.
+*   **Action**: Rebuild the instruction shims. If using CLI commands (`npx total-recall remember` / `forget`), recompilation runs automatically in the background (asynchronously via detached subprocesses) to minimize latency. If editing vault files directly, trigger manual compilation by sending a POST request to `/api/vault/compile` or running `npx total-recall compile`.
 
 ### 6. When troubleshooting connections, port blocks, or sync errors
 *   **Trigger**: If the REST server is unreachable, ports are blocked, or the upstream sync tool encounters errors.
@@ -48,12 +49,12 @@ You MUST actively reference and apply this skill under the following specific ru
 ## ⚡ Core Directives for IDE Agents
 
 ### 1. Zero-Database Sovereign Integrity
-Total Recall operates **entirely database-free**. The local filesystem is the source of truth. Every rule, pattern, decision, concept, preference, and fact exists as a plain Markdown file with semantic YAML frontmatter. Derived indexes are disposable caches. Do not look for PostgreSQL or SQLite databases.
+Total Recall operates **entirely database-free**. The local filesystem is the source of truth. Every rule, pattern, decision, concept, preference, and fact exists as a plain Markdown file with semantic YAML frontmatter. Derived indexes are disposable caches. While the internal Vector Store engine is pluggable and ready for native drop-in indexing engines (such as SQLite-VSS or HNSWLib), the canonical source of truth remains filesystem flat files. Do not look for PostgreSQL or traditional SQL databases.
 
 ### 2. Precise Tool & API Selection Heuristics
 When interacting with the system, choose your interfaces based on the following:
 *   **Local Skills**: Use local skill packages (located in `.agent/skills/`) for complex workspace tasks, testing, and formatting. If a local skill has custom helper scripts, ALWAYS invoke them via your shell command tool instead of running raw standard commands.
-*   **Total Recall Brain (MANDATORY)**: For all semantic searches, memory retrieval, memory writes, and derived index recompilation, **ALWAYS use shell `curl` commands** targeting the REST API endpoints documented below.
+*   **Total Recall Brain (MANDATORY)**: For all semantic searches, memory retrieval, memory writes, and derived index recompilation, **use either the local CLI suite (`npx total-recall`) or shell `curl` commands** targeting the REST API endpoints documented below.
 
 ### 3. Non-Destructive Code Modifications
 When modifying existing rule surfaces or IDE shims (such as `.cursorrules`, `CLAUDE.md`, `GEMINI.md`, etc.), **NEVER** overwrite the developer's custom pre-existing rules. Instead, write compiled absolute invariants inside the managed comment block:
@@ -81,6 +82,54 @@ This spins up a secure local Express server (port 3000, increments dynamically i
 
 ---
 
+## 🛠️ LOCAL CLI SUITE REFERENCE
+
+For local workstation and terminal-based agent workflows, Total Recall provides a CLI command suite:
+
+### 1. Save Memory Node
+```bash
+npx total-recall remember <category> "<content>" [options]
+```
+Save rules, preferences, corrections, and facts.
+*   **Categories**: `invariant`, `preference`, `correction`, `fact`, `concept`, `pattern`, `anti-pattern`, `decision`, `lore`.
+*   **Options**:
+    *   `--global` / `--project`: Target scope. Global writes propagate to all registered projects.
+    *   `--importance <1-5>`: Define relative importance.
+    *   `--priority <level>`: Set priority level (`absolute`, `high`, `normal`, `low`).
+    *   `--modality <type>`: Modality constraints (`must`, `must_not`, `should`, `should_not`, `descriptive`).
+    *   `--slug <custom-slug>` / `--title "<custom-title>"`: Override automatic identifiers.
+    *   `--expires <duration>`: Set expiration lifespan (e.g. `7d`, `2w`, `6h`, `3m`).
+*   *Note*: Spawns an asynchronous background surface compile process immediately on execution to avoid synchronous blockages.
+
+### 2. Delete Memory Node
+```bash
+npx total-recall forget <slug> [options]
+```
+Delete a memory node by slug.
+*   **Options**:
+    *   `--global` / `--project`: Scope layers. If omitted, checks project first, then global.
+    *   `--no-compile`: Skip automatic background recompilation.
+*   *Note*: Spawns an asynchronous background surface compile process immediately on execution.
+
+### 3. Recall / Hybrid Search
+```bash
+npx total-recall recall "<query>" [options]
+```
+Perform semantic/lexical hybrid search across rules, facts, and session history using Reciprocal Rank Fusion (RRF).
+*   **Options**:
+    *   `--top-k, -k <number>`: Number of results (default: 5).
+    *   `--category, -cat <name>`: Filter by SSSS category.
+    *   `--tags, -t <list>`: Filter by tags.
+    *   `--global` / `--project`: Search specific layer.
+
+### 4. Build Memory Vault (Recompile)
+```bash
+npx total-recall compile
+```
+Synchronously rebuild the entire memory index (derived embeddings) and regenerate prompt instruction shims (such as `INSTRUCTIONS.md`, `GEMINI.md`, `AGENTS.md`, etc.).
+
+---
+
 ## 🌐 DIRECT REST API REFERENCE
 
 All requests to the Total Recall REST API must include the Bearer token in the `Authorization` header.

package/scaffold/.agent/skills/total-recall/memory-vault/invariants/operating-instructions.md

@@ -15,7 +15,7 @@ predicate: operate
 object: memory_system
 created: 2026-05-01T00:00:00.000Z
 updated: 2026-05-15T00:00:00.000Z
-last_accessed: 2026-05-15T00:00:00.000Z
+last_accessed: 2026-06-01T06:07:11.601Z
 source:
   type: scaffold
   session_id: scaffold-seed
@@ -36,7 +36,7 @@ sentiment_polarity: directive_must
 sentiment_target: memory_system
 decay:
   half_life_days: 365
-  access_count: 1
+  access_count: 3
 x_temporal_context: 2026-05-26T23:05:06.525Z
 ---
 # Total Recall Operating Protocol

package/scaffold/.agent/skills/total-recall/research-queue.jsonl

@@ -0,0 +1 @@
+{"id":"0efa65c2-0231-4267-a304-e0285e50011e","topic":"Total Recall repository improvement research: SSSS validated write pipeline, filesystem-native memory engines, local-first semantic indexing, Express 5 API hardening, 2026 agent memory architecture patterns","status":"pending","priority":"high","notes":"Queued from repo-wide analysis request on 2026-06-01. Focus on current best practices and meta-patterns for filesystem-native memory OS, validated operation envelopes, append-only logs, cache invalidation, research queue architecture, and secure local-first AI tools.","node_slug":null,"research_phase":"acquisition","created_at":"2026-06-01T06:07:40.102Z","updated_at":"2026-06-01T06:07:40.126Z","completed_at":null,"summary":{"id":"0efa65c2-0231-4267-a304-e0285e50011e","topic":"Total Recall repository improvement research: SSSS validated write pipeline, filesystem-native memory engines, local-first semantic indexing, Express 5 API hardening, 2026 agent memory architecture patterns","status":"pending","phase":"acquisition","last_updated":"2026-06-01T06:07:40.126Z","conclusions":[],"ongoing_directions":["Research project is enqueued / in progress in phase: acquisition"],"sources_count":0}}

package/scaffold/.agent/skills/total-recall/skills/cli-agents/agents.yml

@@ -5,12 +5,7 @@ agents:
     priority: 1
     enabled: true
     exec: flag
-  - name: gemini
-    binary: gemini
-    flags: --sandbox=false --yolo -o json
-    priority: 2
-    enabled: true
-    exec: flag
+
   - name: claude
     binary: claude
     flags: --output-format json --permission-mode bypassPermissions

package/scaffold/.agent/skills/total-recall/skills/ssss/SKILL.md

@@ -9,11 +9,23 @@ schema_version: 2
 
 Structured Semantic Syntax System (ssss) is the core operational substrate of the Total Recall Virtual File System (VFS). This skill guides agents in inspecting, reading, and constructing SSSS-compliant memory nodes, conflict models, and derived indices.
 
+## Spec Version
+
+Current specification: **v0.2 — Draft** (see `references/ssss-spec.md`)
+
+### v0.2 Changes (2026-05-30)
+- Expanded `modality` enum: `must|must_not|should|should_not|descriptive|preference`
+- Expanded `priority` enum: `absolute|high|normal|low` (OPTIONAL, defaults to `normal`)
+- Added §10.1: Projection Manifest requirement with vault-hash staleness detection
+- Added §11.3: Single canonical embedding implementation (no dual systems)
+
 ## Core Directives
 
 1. **Schema Integrity:** Every SSSS node must strictly adhere to the frontmatter schema definitions (Modality, Category, Sentiment).
 2. **Zero-Database Persistence:** Do not look for Postgres or SQLite. Everything lives as a git-versioned Markdown file.
 3. **Decay and Drift Monitoring:** Use decay indicators to manage node half-lives dynamically in background ticks.
+4. **Cached Reads:** All vault reads MUST go through `vault-cache.mjs` (`getNodes()`) — never call `loadNodes()` directly. The cache supports multi-directory (global + project) with per-directory `fs.watch` invalidation.
+5. **Operation Contract:** All agent-generated mutations MUST flow through `processOperation()` (§6). Direct `writeNode()` calls bypass validation, idempotency, authorization, lease protection, and audit logging.
 
 ## Progressive Memory Disclosure
 
@@ -22,6 +34,13 @@ Memory flows through a 3-tier progressive hierarchy:
 * **Tier 2 (Warm):** SKILL.md injects (Category-routed warm capsules).
 * **Tier 3 (Cold):** Full memory vault (Search index files on demand).
 
+## Performance Invariants
+
+* `vault-cache.mjs` is the **single import point** for all node reads. The cache uses `fs.watch` auto-invalidation and supports multiple vault directories simultaneously.
+* `walkMd()` uses `{ withFileTypes: true }` to eliminate per-file `stat()` syscalls.
+* `deleteNode()` scans category directories directly — O(categories) not O(nodes).
+* Surface recompilation (`triggerMutation()`) is debounced with a 2-second quiet period for batch writes.
+
 ## References
 
 * Core SSSS specification: `references/ssss-spec.md`

package/scaffold/.agent/skills/total-recall/skills/ssss/references/ssss-spec.md

@@ -1,6 +1,6 @@
 # SSSS — Structured Semantic Syntax System
 
-**Specification v0.1 — Draft**
+**Specification v0.2 — Draft**
 
 > This is the canonical, vendor-neutral specification for SSSS. It is the ground
 > truth on which all SSSS implementations are built. It is intended to be vendored
@@ -198,8 +198,8 @@ The knowledge primitive. Categories: `invariants`, `patterns`, `anti-patterns`,
 REQUIRED: `type`, `slug`, `category`, `title`, `status`, `schema_version`.
 
 Knowledge-graph fields, REQUIRED when `schema_version: 2`: `confidence` (0..1),
-`importance` (1..5), `modality` (`must|must_not|should|should_not`), `subject`,
-`predicate`, `object`, `sentiment_polarity`
+`importance` (1..5), `modality` (`must|must_not|should|should_not|descriptive|preference`),
+`subject`, `predicate`, `object`, `sentiment_polarity`
 (`directive_must|directive_must_not|descriptive|preference`).
 
 The `subject`/`predicate`/`object` triple SHOULD use stable, language-neutral
@@ -228,7 +228,8 @@ POSIX filesystems; direct writes risk partial-file corruption on crash.
 ```
 
 Memory nodes in the `invariants` category additionally carry `priority: absolute`
-and `immutable: true`.
+and `immutable: true`. The full `priority` enum is `absolute|high|normal|low`;
+`priority` is OPTIONAL on non-invariant categories (defaults to `normal`).
 
 #### `skill`
 
@@ -673,6 +674,30 @@ A host that maintains projections MUST provide a means to (a) rebuild a projecti
 from a vault scan, and (b) detect and repair drift between a projection and the
 vault.
 
+### 10.1 Projection Manifest
+
+A host SHOULD maintain a `MANIFEST.json` (or equivalent) in the derived-artifacts
+directory declaring each projection as disposable and recording provenance:
+
+```jsonc
+{
+  "type": "projection-manifest",
+  "generated_at": "2026-05-30T06:35:00Z",
+  "vault_hash": "sha256:abc123...",       // content hash of the vault at build time
+  "projections": [
+    { "file": "graph-index.jsonl",    "disposable": true },
+    { "file": "memory-layers.jsonl",  "disposable": true },
+    { "file": "embeddings.json",      "disposable": true }
+  ],
+  "rebuild_command": "npx total-recall compile"
+}
+```
+
+The `vault_hash` field enables **staleness detection**: if the current vault hash
+differs from the manifest's hash, the projections are stale and SHOULD be rebuilt.
+This supports **incremental compilation** — a host MAY skip recompilation when the
+hash matches, avoiding redundant I/O on unchanged vaults.
+
 ---
 
 ## 11. The Semantic Layer
@@ -713,6 +738,9 @@ disposable, never source-of-truth, fully rebuildable from the vault.
 
 - It MUST record the `embedding_model` and vector `dim` that produced it. Embeddings
   are not comparable across models; a model change REQUIRES a full reindex.
+- A host MUST maintain exactly **one canonical embedding implementation**. Parallel
+  or duplicate embedding systems (e.g. one in JSON format and another in JSONL)
+  create consistency risks where a node is indexed in one but not the other.
 - Retrieval SHOULD be **hybrid**: an exact/lexical pass (strong for slugs,
   identifiers, and code) fused with a dense semantic pass (strong for meaning and
   cross-lingual matches).
@@ -802,7 +830,7 @@ opaque ID as the slug and keep the human-readable label in `title` / `name`.
 This document is versioned independently of any host and of the conformance
 fixture set.
 
-- The spec version is stated in the document header (currently **v0.1 — Draft**).
+- The spec version is stated in the document header (currently **v0.2 — Draft**).
 - Breaking changes to the file format, the type registry, or the Operation
   Contract increment the spec version.
 - Until **v1.0**, any version MAY introduce breaking changes.

package/src/cli/forget.mjs

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { resolveAgentDir, resolveBrainDir, parseLayerFlag, getBothBrains } from './agent-dir.mjs';
 import { compileSurface } from '../core/surface.mjs';
-import { deleteNode, loadNodes } from '../core/vault.mjs';
+import { deleteNode } from '../core/vault.mjs';
 
 function printHelp() {
   console.log(`
@@ -46,9 +46,15 @@ export default async function forget(args) {
     // Check project first, then global
     if (brains.project) {
       const projVaultDir = path.join(brains.project.brainDir, 'memory-vault');
-      const projNodes = loadNodes(projVaultDir);
-      if (projNodes.some(n => n.slug === slug)) {
-        layer = 'project';
+      // Direct category scan instead of full vault load
+      if (fs.existsSync(projVaultDir)) {
+        const cats = fs.readdirSync(projVaultDir, { withFileTypes: true });
+        for (const cat of cats) {
+          if (cat.isDirectory() && fs.existsSync(path.join(projVaultDir, cat.name, `${slug}.md`))) {
+            layer = 'project';
+            break;
+          }
+        }
       }
     }
     if (layer === 'auto') {
@@ -76,17 +82,17 @@ export default async function forget(args) {
 
   // Recompile unless --no-compile
   if (!noCompile) {
-    console.log('  ⏳ Recompiling active memory surfaces and indexes...');
+    console.log('  ⏳ Recompiling active memory surfaces and indexes in the background...');
     try {
-      const compileResult = await compileSurface({
-        vaultDir,
-        skillsDir,
-        derivedDir,
-        instructionsFile
+      const { spawn } = await import('node:child_process');
+      const child = spawn(process.argv[0], [process.argv[1], 'compile'], {
+        detached: true,
+        stdio: 'ignore'
       });
-      console.log(`  ✅ Recompilation successful! Processed ${compileResult.nodesProcessed} SSSS nodes.`);
+      child.unref();
+      console.log('  ✅ Background compilation started.');
     } catch (err) {
-      console.warn(`  ⚠️  Node deleted, but surface recompilation failed: ${err.message}`);
+      console.warn(`  ⚠️  Node deleted, but background recompilation spawn failed: ${err.message}`);
     }
   }
 }

package/src/cli/ingest/index.mjs

@@ -24,7 +24,8 @@ import { parseSearchHistory } from './parsers/search-history.mjs';
 import { parseChromeBookmarks } from './parsers/chrome-bookmarks.mjs';
 import { parseGoogleKeep } from './parsers/google-keep.mjs';
 import { parseYoutubeHistory } from './parsers/youtube-history.mjs';
-import { writeNode, loadNodes } from '../../core/vault.mjs';
+import { writeNode } from '../../core/vault.mjs';
+import { getNodes } from '../../core/vault-cache.mjs';
 import { resolveBrainDir, parseLayerFlag, getBothBrains, defaultLayerForCategory } from '../../cli/agent-dir.mjs';
 
 /**
@@ -204,7 +205,7 @@ export async function ingestGoogleTakeout(takeoutPath, options = {}) {
   // Load existing vault nodes for dedup
   let existingNodes = [];
   if (fs.existsSync(vaultDir)) {
-    existingNodes = loadNodes(vaultDir);
+    existingNodes = getNodes(vaultDir);
   }
 
   // Run parsers for each detected type

package/src/cli/map.mjs

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { resolveBrainDir, parseLayerFlag, getBothBrains } from './agent-dir.mjs';
-import { loadNodes } from '../core/vault.mjs';
+import { getNodes } from '../core/vault-cache.mjs';
 
 function printHelp() {
   console.log(`
@@ -68,7 +68,7 @@ export default async function map(args) {
     const vaultDir = path.join(l.path, 'memory-vault');
     if (!fs.existsSync(vaultDir)) continue;
 
-    const nodes = loadNodes(vaultDir).map(n => ({ ...n, _layer: l.name }));
+    const nodes = getNodes(vaultDir).map(n => ({ ...n, _layer: l.name }));
     loadedLayers.push({ name: l.name, nodes });
     totalNodesCount += nodes.length;
   }

package/src/cli/rebuild.mjs

@@ -59,7 +59,7 @@ export async function runRebuild(options = {}) {
 
   console.log('🏗️  Recompiling surface from canonical vault...');
   try {
-    const stats = await compileSurface({ vaultDir, skillsDir, derivedDir, instructionsFile });
+    const stats = await compileSurface({ vaultDir, skillsDir, derivedDir, instructionsFile, force: true });
     console.log(`✅ Processed ${stats.nodesProcessed} canonical memory nodes.`);
     console.log(`✅ Injected memory into ${stats.skillsInjected} skill files.`);
     console.log(`✅ Rebuilt graph-index.jsonl, memory-layers.jsonl, and skill-routes.jsonl.`);