total-recall-brain 3.2.3 → 3.4.0

package/frontend/src/pages/IntegrationsPage.tsx

@@ -1,5 +1,5 @@
 import { useMemo, useState, useEffect } from 'react'
-import { getApiBase, listApiKeys, connectClient, fetchActiveIntegrations } from '../api'
+import { getApiBase, listApiKeys, connectClient, fetchActiveIntegrations, fetchExtensionStatus } from '../api'
 import type { ApiKey } from '../api'
 
 type Preset = {
@@ -68,6 +68,7 @@ export default function IntegrationsPage() {
   const [message, setMessage] = useState<{ type: 'success' | 'error'; text: string } | null>(null)
   const [keys, setKeys] = useState<ApiKey[]>([])
   const [activeIdes, setActiveIdes] = useState<string[]>([])
+  const [extStatus, setExtStatus] = useState<{ available: boolean; connected: boolean } | null>(null)
 
   const baseUrl = useMemo(() => {
     const configured = getApiBase()
@@ -91,6 +92,12 @@ export default function IntegrationsPage() {
       })
       .catch(() => {})
 
+    fetchExtensionStatus()
+      .then(res => {
+        if (active) setExtStatus(res)
+      })
+      .catch(() => {})
+
     return () => { active = false }
   }, [])
 
@@ -221,6 +228,138 @@ export default function IntegrationsPage() {
         gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))',
         gap: 16,
       }}>
+        {/* Chrome Extension Integration Card */}
+        <div style={{
+          border: '1px solid var(--border)',
+          background: 'var(--bg-secondary)',
+          borderRadius: 12,
+          padding: 18,
+          display: 'flex',
+          flexDirection: 'column',
+          gap: 12,
+          position: 'relative',
+        }}>
+          <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start', gap: 12 }}>
+            <div>
+              <h3 style={{ margin: '0 0 4px' }}>Chrome Extension</h3>
+              <div style={{ color: 'var(--text-tertiary)', fontSize: 12 }}>Browser Overlay Panel & Capture</div>
+            </div>
+            {extStatus ? (
+              extStatus.connected ? (
+                <span style={{
+                  display: 'inline-flex',
+                  alignItems: 'center',
+                  gap: 6,
+                  padding: '4px 8px',
+                  borderRadius: 6,
+                  background: 'rgba(16, 185, 129, 0.1)',
+                  border: '1px solid rgba(16, 185, 129, 0.3)',
+                  fontSize: 12,
+                  color: '#34d399',
+                  fontWeight: 500,
+                }}>
+                  <span style={{
+                    width: 8,
+                    height: 8,
+                    borderRadius: '50%',
+                    background: '#10b981',
+                    boxShadow: '0 0 8px #10b981',
+                  }} />
+                  Connected
+                </span>
+              ) : (
+                <span style={{
+                  display: 'inline-flex',
+                  alignItems: 'center',
+                  gap: 6,
+                  padding: '4px 8px',
+                  borderRadius: 6,
+                  background: 'rgba(245, 158, 11, 0.1)',
+                  border: '1px solid rgba(245, 158, 11, 0.3)',
+                  fontSize: 12,
+                  color: '#fbbf24',
+                  fontWeight: 500,
+                }}>
+                  <span style={{ width: 8, height: 8, borderRadius: '50%', background: '#f59e0b' }} />
+                  Not Connected
+                </span>
+              )
+            ) : (
+              <span style={{
+                display: 'inline-flex',
+                alignItems: 'center',
+                gap: 6,
+                padding: '4px 8px',
+                borderRadius: 6,
+                background: 'rgba(255, 255, 255, 0.05)',
+                border: '1px solid rgba(255, 255, 255, 0.1)',
+                fontSize: 12,
+                color: 'var(--text-tertiary)'
+              }}>
+                <span style={{ width: 8, height: 8, borderRadius: '50%', background: '#94a3b8' }} />
+                Checking...
+              </span>
+            )}
+          </div>
+
+          <div style={{ fontSize: 12, color: 'var(--text-secondary)' }}>
+            Scopes utilized: <code>chat:write, memory:read, memory:write</code>
+          </div>
+
+          <div style={{
+            background: 'var(--bg-primary)',
+            border: '1px solid var(--border)',
+            borderRadius: 8,
+            padding: 10,
+            fontSize: 13,
+            color: 'var(--text-secondary)',
+            lineHeight: '1.4'
+          }}>
+            Install the Total Recall extension to passively capture context, store quick notes, and access the active brain search overlay inside any Chrome tab.
+          </div>
+
+          <div style={{
+            background: 'var(--bg-primary)',
+            border: '1px solid var(--border)',
+            borderRadius: 8,
+            padding: 10,
+            fontFamily: 'monospace',
+            fontSize: 11,
+            whiteSpace: 'pre-wrap',
+            color: 'var(--text-tertiary)',
+          }}>
+            1. Download zip & unzip locally.{"\n"}
+            2. Go to chrome://extensions in browser.{"\n"}
+            3. Enable "Developer mode" (top right).{"\n"}
+            4. Click "Load unpacked" & select unzipped folder.
+          </div>
+
+          <div style={{ display: 'flex', gap: 10, marginTop: 'auto', paddingTop: 8 }}>
+            <a
+              href={`${baseUrl}/api/extension/download`}
+              download
+              className="btn btn-sm btn-primary"
+              style={{
+                background: 'linear-gradient(135deg, #3b82f6 0%, #1d4ed8 100%)',
+                border: 'none',
+                boxShadow: '0 2px 4px rgba(59, 130, 246, 0.3)',
+                fontWeight: 600,
+                cursor: 'pointer',
+                textDecoration: 'none',
+                display: 'inline-flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                padding: '6px 12px',
+                borderRadius: '6px',
+                color: '#fff',
+                fontSize: '12px'
+              }}
+            >
+              ⬇ Download Extension Zip
+            </a>
+          </div>
+        </div>
+
         {filteredPresets.map(preset => {
           const snippet = preset.snippet(baseUrl)
           
@@ -252,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.2.3",
+  "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/init.mjs

@@ -533,6 +533,36 @@ export default async function init(args) {
     if (opts.token) brainCfg.token = opts.token;
     fs.writeFileSync(path.join(cfgDir, 'brain.json'), JSON.stringify(brainCfg, null, 2), { mode: 0o600 });
     logOk(`Registered brain at ${opts.brain}. Run \`npx total-recall sync\` to pull instructions.`);
+  } else {
+    // Zero-config bootstrap: auto-generate localhost brain.json and valid Developer PAT out-of-the-box
+    const cfgDir = path.join(brainDir, 'config');
+    fs.mkdirSync(cfgDir, { recursive: true });
+    const brainJsonPath = path.join(cfgDir, 'brain.json');
+    let needsBootstrap = false;
+    let brainCfg = {};
+    if (fs.existsSync(brainJsonPath)) {
+      try {
+        brainCfg = JSON.parse(fs.readFileSync(brainJsonPath, 'utf8'));
+        if (!brainCfg.url || !brainCfg.token) needsBootstrap = true;
+      } catch {
+        needsBootstrap = true;
+      }
+    } else {
+      needsBootstrap = true;
+    }
+
+    if (needsBootstrap) {
+      try {
+        const { issueKey } = await import('../server/keys.mjs');
+        const keyData = issueKey('Default Local Developer Key', { scopes: ['*'] });
+        brainCfg.url = brainCfg.url || 'http://localhost:3000';
+        brainCfg.token = brainCfg.token || keyData.token;
+        fs.writeFileSync(brainJsonPath, JSON.stringify(brainCfg, null, 2), { mode: 0o600 });
+        logOk(`Bootstrap configuration successfully generated and pre-authorized at ${brainCfg.url}`);
+      } catch (err) {
+        logWarn(`Could not auto-generate bootstrap developer key: ${err.message}`);
+      }
+    }
   }
 
   let dashboardUrl = '';

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.`);

package/src/cli/remember.mjs

@@ -3,7 +3,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { resolveAgentDir, resolveBrainDir, parseLayerFlag, getBothBrains, defaultLayerForCategory } from './agent-dir.mjs';
 import { compileSurface } from '../core/surface.mjs';
-import { writeNode } from '../core/vault.mjs';
+import { writeNodeValidated } from '../core/validated-write.mjs';
 
 function printHelp() {
   console.log(`
@@ -287,20 +287,30 @@ export default async function remember(args) {
     node.immutable = true;
   }
 
-  writeNode(node, vaultDir);
+  const vaultResult = writeNodeValidated(node, vaultDir);
+  if (!vaultResult.success) {
+    console.error(`  ❌ Validation failed: ${vaultResult.validation.errors.join('; ')}`);
+    if (vaultResult.repair) {
+      console.error(`  🔧 Repair hints:`);
+      for (const fe of vaultResult.repair.field_errors || []) {
+        console.error(`     • ${fe.field}: ${fe.issue}`);
+      }
+    }
+    process.exit(1);
+  }
   console.log(`  ✅ Permanent SSSS memory node created ${layerLabel} in vault: memory-vault/${category}/${finalSlug}.md`);
 
-  // Instantly recompile instructions and vector indexes in the exact same turn!
-  console.log('  ⏳ Recompiling active memory surfaces and indexes...');
+  // Recompile active memory surfaces and indexes in the background to avoid blocking the CLI call.
+  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(`  ⚠️  Memory saved, but surface recompilation failed: ${err.message}`);
+    console.warn(`  ⚠️  Memory saved, but background recompilation spawn failed: ${err.message}`);
   }
 }

package/src/cli/setup.mjs

@@ -541,8 +541,17 @@ export default async function setup(args) {
       ], { stdio: 'inherit' });
       if (result.status !== 0) throw new Error('Local deploy failed');
       ok('Local deploy complete!');
+
+      // Auto-issue a local developer key for zero-config extension / IDE connection
+      try {
+        const { issueKey } = await import('../server/keys.mjs');
+        const keyData = issueKey('Default Local Developer Key', { scopes: ['*'] });
+        pat = keyData.token;
+      } catch (err) {
+        warn(`Could not auto-generate local developer key: ${err.message}`);
+      }
     }
-    brainUrl = 'http://127.0.0.1:3000';
+    brainUrl = 'http://localhost:3000';
   }
 
   // ── Step 3: Domain (optional) ────────────────────────────────────────────────