total-recall-brain 3.3.0 → 3.4.0

package/README.md

@@ -1,6 +1,6 @@
 # Total Recall — SSSS Sovereign AI OS
 
-[![Version](https://img.shields.io/badge/version-3.0.0-indigo.svg)](package.json)
+[![Version](https://img.shields.io/badge/version-3.3.0-indigo.svg)](package.json)
 [![License](https://img.shields.io/badge/license-MIT-emerald.svg)](LICENSE)
 [![Continuous Integration](https://img.shields.io/badge/CI-passing-teal.svg)](.github/workflows/test.yml)
 

package/extension/background.js

@@ -75,7 +75,7 @@ function showBadge(text, color) {
 // ---------------------------------------------------------------------------
 // Message listener (popup, content-script, sidepanel → background)
 // ---------------------------------------------------------------------------
-chrome.runtime.onMessage.addListener((msg, _sender, sendResponse) => {
+chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
   if (msg.type === 'QUERY_BRAIN') {
     search(msg.query, msg.topK || 3)
       .then(data => sendResponse({ memories: data.results || [] }))
@@ -96,4 +96,16 @@ chrome.runtime.onMessage.addListener((msg, _sender, sendResponse) => {
       .catch(() => sendResponse({ connected: false }));
     return true;
   }
+
+  if (msg.type === 'OPEN_SIDE_PANEL') {
+    const tabId = sender.tab?.id;
+    if (!chrome.sidePanel?.open || !tabId) {
+      sendResponse({ success: false, error: 'Side panel is unavailable for this tab.' });
+      return false;
+    }
+    chrome.sidePanel.open({ tabId })
+      .then(() => sendResponse({ success: true }))
+      .catch(err => sendResponse({ success: false, error: err.message }));
+    return true;
+  }
 });

package/extension/content-script.js

@@ -112,8 +112,25 @@
     document.body.appendChild(pillHost);
   }
 
+  function isBlocked(blocklist) {
+    if (!Array.isArray(blocklist) || blocklist.length === 0) return false;
+    let host = '';
+    try {
+      host = new URL(pageContext.url).hostname.toLowerCase();
+    } catch {
+      return false;
+    }
+    return blocklist.some((entry) => {
+      const pattern = String(entry || '').trim().toLowerCase();
+      return pattern && (host === pattern || host.endsWith(`.${pattern}`) || pageContext.url.toLowerCase().includes(pattern));
+    });
+  }
+
   // ---- Query brain after delay ----
-  function queryBrain() {
+  async function queryBrain() {
+    const { passiveTracking = false, blocklist = [] } = await chrome.storage.sync.get(['passiveTracking', 'blocklist']);
+    if (!passiveTracking || isBlocked(blocklist)) return;
+
     const query = pageContext.title || pageContext.url;
     if (!query) return;
 

package/extension/lib/brain-client.js

@@ -6,8 +6,21 @@
   const DEFAULT_BRAIN_URL = 'http://127.0.0.1:3000';
 
   async function getConfig() {
-    const config = await chrome.storage.sync.get(['brainUrl', 'pat']);
+    const [localConfig, syncConfig] = await Promise.all([
+      chrome.storage.local.get(['brainUrl', 'pat']),
+      chrome.storage.sync.get(['brainUrl', 'pat'])
+    ]);
     const pre = self.PreConfigured || {};
+    const config = {
+      brainUrl: localConfig.brainUrl || syncConfig.brainUrl,
+      pat: localConfig.pat || syncConfig.pat
+    };
+
+    if (syncConfig.pat && !localConfig.pat) {
+      await chrome.storage.local.set({ pat: syncConfig.pat });
+      await chrome.storage.sync.remove('pat');
+    }
+
     return {
       brainUrl: config.brainUrl || pre.brainUrl || DEFAULT_BRAIN_URL,
       pat: config.pat || pre.pat || ''
@@ -67,13 +80,13 @@
     return res.json();
   }
 
-  // Self-heal stale storage: if preconfigured values exist, automatically write them to chrome.storage.sync
+  // Self-heal stale storage: if preconfigured values exist, write them to extension-local storage.
   try {
-    if (typeof chrome !== 'undefined' && chrome.storage && chrome.storage.sync) {
-      chrome.storage.sync.get(['brainUrl', 'pat']).then((config) => {
+    if (typeof chrome !== 'undefined' && chrome.storage && chrome.storage.local) {
+      chrome.storage.local.get(['brainUrl', 'pat']).then((config) => {
         const pre = self.PreConfigured || {};
         if (pre.pat && (!config.pat || config.pat !== pre.pat)) {
-          chrome.storage.sync.set({ brainUrl: pre.brainUrl, pat: pre.pat });
+          chrome.storage.local.set({ brainUrl: pre.brainUrl, pat: pre.pat });
         }
       });
     }

package/extension/options/options.js

@@ -13,12 +13,14 @@
 
   // ---- Load saved settings ----
   async function loadSettings() {
-    const settings = await chrome.storage.sync.get([
-      'brainUrl',
-      'pat',
+    const [localSettings, syncSettings] = await Promise.all([
+      chrome.storage.local.get(['brainUrl', 'pat']),
+      chrome.storage.sync.get([
       'blocklist',
       'captureGranularity'
+      ])
     ]);
+    const settings = { ...syncSettings, ...localSettings };
 
     const pre = self.PreConfigured || {};
     brainUrlInput.value = settings.brainUrl || pre.brainUrl || 'http://127.0.0.1:3000';
@@ -48,9 +50,12 @@
       const granularityRadio = document.querySelector('input[name="granularity"]:checked');
       const captureGranularity = granularityRadio ? granularityRadio.value : 'minimal';
 
-      await chrome.storage.sync.set({
+      await chrome.storage.local.set({
         brainUrl: brainUrlInput.value.trim() || 'http://127.0.0.1:3000',
         pat: patInput.value.trim(),
+      });
+      await chrome.storage.sync.remove('pat');
+      await chrome.storage.sync.set({
         blocklist,
         captureGranularity
       });

package/frontend/index.html

@@ -5,6 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="description" content="Total Recall — Sovereign AI Brain Dashboard. Memory explorer, chat interface, code sandbox, and system health monitoring." />
     <meta name="theme-color" content="#0a0a0f" />
+    <link rel="manifest" href="/manifest.json" />
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
@@ -13,5 +14,12 @@
   <body>
     <div id="root"></div>
     <script type="module" src="/src/main.tsx"></script>
+    <script>
+      if ('serviceWorker' in navigator) {
+        window.addEventListener('load', () => {
+          navigator.serviceWorker.register('/sw.js').catch(() => {});
+        });
+      }
+    </script>
   </body>
 </html>

package/frontend/src/api.ts

@@ -563,7 +563,7 @@ export async function resolveConflict(
 
 export async function saveMemory(slug: string, node: Partial<MemoryNode>): Promise<MemoryNode> {
   const res = await apiFetch(`${API_BASE}/api/memory/${slug}`, {
-    method: "PUT",
+    method: "PATCH",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(node),
   })
@@ -685,4 +685,3 @@ export async function fetchExtensionStatus(): Promise<{ available: boolean; conn
   if (!res.ok) return { available: false, connected: false }
   return res.json()
 }
-

package/frontend/src/pages/ChatPage.tsx

@@ -57,7 +57,10 @@ export default function ChatPage({ activeBrainId, onBrainChange }: { activeBrain
 
   // Model Selector state
   const [availableModels, setAvailableModels] = useState<string[]>([])
-  const [selectedModel, setSelectedModel] = useState<string>(() => localStorage.getItem('selectedModel') || '')
+  const [selectedModel, setSelectedModel] = useState<string>(() => {
+    const saved = localStorage.getItem('selectedModel');
+    return (saved && saved !== 'gemini') ? saved : 'antigravity';
+  })
   const [selectedSubModel, setSelectedSubModel] = useState<string>(() => localStorage.getItem('selectedSubModel') || '')
   const [geminiModels, setGeminiModels] = useState<{ id: string; displayName: string }[]>([])
   const [showModelDropdown, setShowModelDropdown] = useState(false)
@@ -104,27 +107,27 @@ export default function ChatPage({ activeBrainId, onBrainChange }: { activeBrain
       .then(health => {
         const agents = health.cli_agents && health.cli_agents.length > 0
           ? health.cli_agents
-          : ['antigravity', 'gemini', 'claude', 'codex'];
+          : ['antigravity', 'claude', 'codex'];
         setAvailableModels(agents);
         
         const saved = localStorage.getItem('selectedModel');
         if (saved && agents.includes(saved)) {
           setSelectedModel(saved);
         } else {
-          const defaultAgent = agents.includes('gemini') ? 'gemini' : agents[0];
+          const defaultAgent = agents.includes('antigravity') ? 'antigravity' : agents[0];
           setSelectedModel(defaultAgent);
           localStorage.setItem('selectedModel', defaultAgent);
         }
       })
       .catch(() => {
-        const agents = ['antigravity', 'gemini', 'claude', 'codex'];
+        const agents = ['antigravity', 'claude', 'codex'];
         setAvailableModels(agents);
         const saved = localStorage.getItem('selectedModel');
         if (saved && agents.includes(saved)) {
           setSelectedModel(saved);
         } else {
-          setSelectedModel('gemini');
-          localStorage.setItem('selectedModel', 'gemini');
+          setSelectedModel('antigravity');
+          localStorage.setItem('selectedModel', 'antigravity');
         }
       })
 

package/frontend/src/pages/IntegrationsPage.tsx

@@ -391,10 +391,12 @@ export default function IntegrationsPage() {
           )
 
           if (matchingKey) {
-            if (matchingKey.hit_count > 0) {
+            if (matchingKey.hit_count > 0 || preset.id === 'antigravity') {
               const lastUsedStr = matchingKey.last_used_at 
                 ? ` (Active ${new Date(matchingKey.last_used_at).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })})`
-                : ''
+                : preset.id === 'antigravity'
+                  ? ' (Active Now)'
+                  : ''
               statusBadge = (
                 <span style={{
                   display: 'inline-flex',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.3.0",
+  "version": "3.4.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/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.`);