total-recall-brain 3.1.0

package/bin/total-recall.mjs

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+
+/**
+ * total-recall CLI
+ *
+ * Entry point for `npx total-recall <command>`.
+ * Routes subcommands to handlers in src/cli/.
+ *
+ * Usage:
+ *   npx total-recall init            Bootstrap Total Recall into an existing project
+ *   npx total-recall setup           Interactive setup wizard (provider → deploy → connect IDEs)
+ *   npx total-recall deploy          Provision a target machine
+ *   npx total-recall import          Import existing rule files into the vault
+ *   npx total-recall compile         Rebuild indexes + INSTRUCTIONS.md (alias: rebuild)
+ *   npx total-recall dream           Trigger a dream cycle
+ *   npx total-recall ingest          Ingest IDE conversation logs or Google Takeout data
+ *   npx total-recall connect         Configure an IDE or external system
+ *   npx total-recall sync            Pull remote brain instructions into workspace
+ *   npx total-recall lint            Validate vault nodes against schema v2
+ *   npx total-recall daemon <cmd>    start | stop | status
+ *   npx total-recall status          Show brain connection and sync state
+ *   npx total-recall generate-pat    Issue a hashed Personal Access Token
+ *   npx total-recall hash-password   Generate a dashboard password hash
+ *   npx total-recall backup          Create encrypted VFS tarball
+ *   npx total-recall restore <path>  Restore from backup
+ *   npx total-recall snapshot        Manage point-in-time VFS snapshots
+ *   npx total-recall migrate         Run SSSS schema migrations
+ *   npx total-recall chat            Interactive terminal chat
+ *   npx total-recall friction        Analyze logs for workflow bottlenecks
+ *   npx total-recall upgrade         Swap kernel model
+ *   npx total-recall research <cmd>  Manage/query ongoing autonomous research agenda
+ *   npx total-recall share [url]     Share a URL or text snippet to the brain
+ *   npx total-recall --help          Show this help
+ */
+
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_DIR = path.join(__dirname, '..', 'src', 'cli');
+
+const COMMANDS = {
+  init:     'init.mjs',
+  setup:    'setup.mjs',
+  start:    'start.mjs',
+  deploy:   'deploy.mjs',
+  doctor:   'doctor.mjs',
+  backup:   'backup.mjs',
+  dream:    'dream.mjs',
+  lint:     'lint.mjs',
+  daemon:   'daemon.mjs',
+  restore:  'restore.mjs',
+  upgrade:  'upgrade.mjs',
+  friction: 'friction.mjs',
+  chat:     'chat.mjs',
+  status:   'status.mjs',
+  remember: 'remember.mjs',
+  forget:   'forget.mjs',
+  recall:   'recall.mjs',
+  search:   'recall.mjs',
+  research: 'research.mjs',
+  share:    'share.mjs',
+  'generate-pat': 'generate-pat.mjs',
+  'hash-password': 'hash-password.mjs',
+  'reset-password': 'reset-password.mjs',
+  compile:  'rebuild.mjs',
+  rebuild:  'rebuild.mjs',
+  snapshot: 'snapshot.mjs',
+  migrate:  'migrate.mjs',
+  ingest:   'ingest.mjs',
+  import:   'import-rules.mjs',
+  connect:  'connect.mjs',
+  sync:     'sync.mjs',
+  relay:    'relay.mjs',
+  uninstall: 'uninstall.mjs',
+  map:      'map.mjs',
+  brain:    'brain.mjs',
+  config:   'config.mjs',
+  skill:    'skill.mjs',
+  help:     'help.mjs',
+};
+function printHelp() {
+  console.log(`
+  total-recall — Sovereign AI System CLI
+
+  Usage: total-recall <command> [options]
+
+  Commands:
+    init                Bootstrap Total Recall into an existing project repo
+    setup               Interactive wizard: provider → API key → provision → connect IDEs
+    start [--port N]    Start the brain server in the foreground (alias for running the server directly)
+    deploy              Provision a target machine (Caddy/TLS, system services, VFS setup, environment checks)
+    doctor              Run environment diagnostics and verify dependency health
+    dream               Manually trigger a dream cycle (Light → REM → Deep)
+    lint                Validate all vault nodes against SSSS schema v2
+    daemon <start|stop|status>  Manage the background daemon
+    status              Show server health, active deploy mode, dashboard URL, tunnel PID, and daemon state
+    backup [options]    Create encrypted VFS tarball, push git backup, or Obsidian sync
+    restore <path>      Restore from an encrypted backup
+    upgrade --model <n> Swap the kernel model (e.g., gemma5-32b)
+    friction            Analyze logs to detect workflow bottlenecks
+    chat                Interactive terminal chat with the Sovereign OS
+    remember            Remember new rules, preferences, or corrections in real time
+    forget <slug>       Delete a memory node by slug (with auto-recompile)
+    recall              Recall semantic memory or search existing knowledge/rules/session-history
+    map                 Visualize memory vault category trees and link relationships
+    brain <cmd>         Manage registered brains and context resolution (list, status, register, unregister)
+    research <command>  Manage/query ongoing autonomous research agenda (list, add, show, report, cancel)
+    share [url]         Share a URL or text snippet to the brain (auto-routes to remember or research)
+    config <get|set>    Read, write, and toggle UI, security, and budget settings
+    skill <command>     Manage AI agent skills: find, install, scan, list, remove
+    generate-pat        Issue a PAT; stores only a hash in keys.jsonl
+    hash-password       Generate a bcrypt dashboard password hash
+    reset-password      Reset the dashboard admin password and force a change on login
+    compile             Alias for rebuild: deterministically rebuild projections
+    rebuild [--check]   Detect index drift and deterministically rebuild projections
+    snapshot            Manage fast point-in-time VFS snapshots and rollbacks
+    migrate             Run backwards-incompatible SSSS schema migrations
+    import [--dir <path>] [--force]   Import existing AGENTS.md, .cursorrules, CLAUDE.md, etc.
+                                     into the vault (run before compile on first install)
+    ingest [--watch]    Ingest IDE conversation logs (Claude Code, Codex, Gemini, etc.)
+    ingest google-takeout <path>  Ingest Google Takeout export data
+    connect <client>    Configure Cursor, Claude Code, Codex, UltraChat, Gemini, etc.
+    sync [--watch]      Pull remote brain instructions into the current workspace
+    relay <cmd>         Local background relay: ship IDE sessions to remote brain
+                        Commands: start | stop | status | once | install | uninstall
+    uninstall           Completely uninstall all services, launchd agents, VFS, and shims
+    help <topic>        Interactive offline documentation, SSSS reference, and system help
+
+
+
+  Autonomous operations (sync, compile, backup) are now handled by the
+  Cloud Agent via SSSS task nodes in .agent/scheduler/queue/.
+  The agent cron trigger (every 5 min) processes these automatically.
+
+  Options:
+    --help, -h          Show this help message
+    --version, -v       Show version
+
+  Examples:
+    npx total-recall deploy
+    npx total-recall dream
+    npx total-recall daemon status
+`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === '--help' || command === '-h') {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (command === '--version' || command === '-v') {
+    const pkg = await import(path.join(__dirname, '..', 'package.json'), { with: { type: 'json' } });
+    console.log(`total-recall v${pkg.default.version}`);
+    process.exit(0);
+  }
+
+  const handlerFile = COMMANDS[command];
+  if (!handlerFile) {
+    // Check if it is a dynamic integration command configured in the VFS
+    try {
+      const { agentDir } = await import('../src/core/config.mjs');
+      const fs = await import('node:fs');
+      const integrationPath = path.join(agentDir, 'skills', 'total-recall', 'integrations', `${command}.md`);
+      
+      if (fs.existsSync(integrationPath)) {
+        const action = args[1];
+        if (!action) {
+          console.error(`Error: Missing action name for service "${command}".`);
+          console.error(`Usage: npx total-recall ${command} <action> [options]`);
+          process.exit(1);
+        }
+
+        // Parse CLI options (e.g. --owner value)
+        const options = {};
+        for (let i = 2; i < args.length; i++) {
+          const arg = args[i];
+          if (arg.startsWith('--')) {
+            const key = arg.slice(2);
+            const val = args[i + 1];
+            if (val && !val.startsWith('--')) {
+              options[key] = val;
+              i++;
+            } else {
+              options[key] = true;
+            }
+          }
+        }
+
+        const { default: dispatch } = await import('../src/cli/integration-dispatcher.mjs');
+        const result = await dispatch(command, action, options);
+        console.log(typeof result === 'object' ? JSON.stringify(result, null, 2) : result);
+        process.exit(0);
+      }
+    } catch (err) {
+      console.error(`Error executing integration command: ${err.message}`);
+      process.exit(1);
+    }
+
+    console.error(`Unknown command: ${command}`);
+    console.error(`Run 'total-recall --help' for usage.`);
+    process.exit(1);
+  }
+
+  const handlerPath = path.join(CLI_DIR, handlerFile);
+
+  try {
+    const handler = await import(handlerPath);
+    if (handler.run) {
+      await handler.run(process.argv);
+    } else {
+      await handler.default(process.argv.slice(3));
+    }
+  } catch (err) {
+    if (err.code === 'ERR_MODULE_NOT_FOUND') {
+      console.error(`Command '${command}' is not yet implemented.`);
+      console.error(`Expected handler at: ${handlerPath}`);
+      process.exit(1);
+    }
+    console.error(`Error executing '${command}':`, err.message);
+    process.exit(1);
+  }
+}
+
+main();

package/docs/ARCHITECTURE.md

@@ -0,0 +1,251 @@
+# Total Recall — System Architecture
+
+> Verified against codebase: `relay.mjs`, `session-watcher.mjs`, `daemon-loop.mjs`, `surface.mjs`, `scheduler.mjs`, `embeddings.mjs`, `dispatch.mjs`, `vault-cache.mjs`, `config.mjs`, `sandbox.mjs`.
+> Last Updated: May 25, 2026
+
+---
+
+## ⚡ The One-Sentence Summary
+
+Total Recall is a **database-free, local background session relay + remote intelligence brain** system: a lightweight relay daemon watches local IDE conversation files and ships updates to your remote brain server, which employs high-fidelity vector semantic search (Google `gemini-embedding-2` with OpenAI fallback), structured cost-limiting controls, and a headless CLI agent execution framework to ingest history, resolve rules, and recompile a **5-line progressive disclosure pointer shim** that all IDEs inherit automatically.
+
+---
+
+## 🏗️ Two-Component Topology
+
+```
+YOUR WORKSTATION                                 YOUR BRAIN SERVER
+(any machine you write code on)                  (Mac Mini, Vast.ai VPS, local host, etc.)
+
+┌─────────────────────────────┐                  ┌──────────────────────────────────┐
+│  IDE Session Logs           │                  │  Total Recall REST Server        │
+│                             │                  │                                  │
+│  ~/.claude/projects/        │     relay        │  POST /api/sessions/ingest       │
+│  ~/.cursor/projects/        │  ─────────────►  │                                  │
+│  ~/.codex/sessions/         │   (every 60s,    │  Headless CLI Agent Dispatch     │
+│  ~/.gemini/antigravity/     │    new files     │  (spawns subagents from registry │
+│  ~/Library/.../chatSessions/│    only)         │  to run dream & research tasks)  │
+│                             │                  │                                  │
+│  npx total-recall relay     │  ◄─────────────  │  Google gemini-embedding-2       │
+│  (launchd/systemd service)  │   INSTRUCTIONS.  │  (and OpenAI fallback) handles   │
+│                             │   md pulled      │  semantic search & indexing      │
+│  CLAUDE.md                  │   (connect)      │                                  │
+│  MEMORY.md (5-line shim)    │                  │ VFS (.agent/skills/total-recall/)│
+│  .cursor/rules/             │                  │ ├── INSTRUCTIONS.md (shim)       │
+│  GEMINI.md                  │                  │ └── memory-vault/                │
+└─────────────────────────────┘                  └──────────────────────────────────┘
+```
+
+### Component 1: The Session Relay (Workstation client)
+
+**File:** `src/cli/relay.mjs`
+
+The session relay is a silent Node.js daemon that:
+1. Watches active IDE log folders for changes to active conversation files.
+2. Ingests modified lines and pushes them to the brain's REST API (`POST /api/sessions/ingest`).
+3. Employs filesystem `mtime` modification timestamps to prevent redundant network transmissions.
+4. Standardized as macOS launchd plists or Linux systemd user services that run on startup.
+
+**Watched Locations:**
+
+| Client / Editor | Directory Path | Log Format |
+| :--- | :--- | :--- |
+| **Claude Code** | `~/.claude/projects/` | Line-delimited JSONL |
+| **Codex CLI** | `~/.codex/sessions/` | JSON log sequences |
+| **Cursor** | `~/.cursor/projects/` | SQLite/JSON logs |
+| **VS Code Copilot** | `~/Library/Application Support/Code/User/workspaceStorage/*/chatSessions/` | JSON delta sequences |
+| **Antigravity** | `~/.gemini/antigravity/brain/` | JSONL history logs |
+
+---
+
+### Component 2: The Sovereign Brain Server
+
+The brain server runs the primary REST API, compiles instructions, runs the background daemons, and maintains the Virtual File System (VFS).
+
+---
+
+### Component 3: The Setup Web Wizard (Graphical Browser Installer)
+
+**Files:** `src/cli/deploy-ui.mjs`, `src/cli/wizard.html`
+
+The Setup Web Wizard is served by a local Express instance during installation/deployment (`npx total-recall deploy --ui` or `setup`) and provides a premium, graphical onboarding dashboard that opens automatically in your default macOS/Linux web browser:
+1. **Interactive Provisioning Phases**: Steps through deployment targets (Local, network SSH computer, renting a GPU in the cloud via Vast.ai credentials, or your own VPS), SSL auto-TLS configurations, and dashboard admin password hashing.
+2. **One-Click Automated Installer**: Spawns an internal Server-Sent Events (SSE) progress pipeline, emitting live terminal compilation, model download, and installation logs directly to the browser screen.
+3. **Omni-Channel Integration Selector**: A multi-select visual panel to wire up Claude Code, Codex, Cursor, VS Code Copilot, Gemini CLI, Aider, and Obsidian, plus installing launchd/systemd background relays.
+4. **Credential Restoration**: Integrates with local persistent fallbacks, automatically identifying and restoring AES-encrypted tokens and bcrypt password hashes from `~/.agent/secrets.enc` or `.agent/secrets.enc` to avoid credential resets on fresh setups.
+
+---
+
+#### 1. ⚡ High-Speed Semantic Vector Indexing
+- **Primary Model**: Google `gemini-embedding-2` (768 dimensions), with fallback vectors configured in the active API models registry (e.g., OpenAI `text-embedding-3-small`).
+- **File-Native Indexes**: Vector indexes are written directly to plain JSONL (`embeddings.jsonl`) under the meta-skill's `memory-derived/` directory, backed by a high-speed cosine memory cache (`embeddings-cache.json`) for <50ms lookup times.
+- **Auto-Healing Dimension Mismatch Purging**: If you switch embedding models (e.g. from a 384-dim Ollama model to the 768-dim Google API), the engine detects the dimension length mismatch, automatically clears out the obsolete cache files, and indexes the entire vault cleanly from scratch.
+
+#### 2. 🤖 Headless CLI Agent Dispatch Framework
+Total Recall completely eliminates heavy local GPU hardware overhead (Ollama and local VM models are fully deprecated). Instead, cognitive tasks (post-mortems, web research crawls, and dream cycle updates) are routed to specialized, headlessly spawned CLI agents running via non-interactive subshells (`spawnSync`):
+
+- **Antigravity CLI** (`antigravity`): Ingests massive token context bounds for broad log post-mortems and repository-wide gap discovery.
+- **Claude Code** (`claude`): Resolves complex logical rules, verifies integration tests, and performs precise SSSS ontology checking.
+- **Codex CLI** (`codex`): Executes sandboxed test suites and automated file writes.
+
+All dispatches are configured via the prioritized execution registry in `~/.agent/skills/total-recall/skills/cli-agents/agents.yml` and utilize the **Dynamic Model Selector (`resolveGenerativeModel`)** to dynamically translate general aliases (`flash`, `pro`, `default`) into the active, optimal model endpoints.
+
+#### 3. 📂 Progressive Disclosure Surface Compiler
+- Avoids prompt bloat by keeping active system prompts under 1,000 tokens.
+- **Tier 1 (Hot Invariants)**: Absolutely binding rules (`priority: absolute` and `modality: must|must_not`) are compiled into a tiny, **5-line progressive pointer shim** that references the meta-skill `SKILL.md` system.
+- **Tier 2 (Contextual Skills)**: The hybrid BM25 + TF-IDF router (`surface.mjs`) dynamically injects only the top-7 relevant memory nodes into domain-specific skill manifests on demand.
+
+#### 4. 🗄️ Unified Merged Vault Caching (`vault-cache.mjs`)
+- To eliminate expensive per-request disk scanning operations, `vault-cache.mjs` starts a persistent `fs.watch` file watcher over the SSSS memory directories, caching nodes in-memory.
+- Standard read requests resolve instantly against the memory cache.
+- In-process writes (POST, PUT, PATCH, DELETE) automatically call `invalidate()` to guarantee real-time updates are reflected instantly without waiting for disk watcher polls.
+
+---
+
+## 🧠 The Dual-Layer Brain Cascade
+
+Total Recall partitions your sovereign brain memory into two virtual directories:
+
+```
+~ (User Home)
+└── .agent/skills/total-recall/                 <-- GLOBAL BRAIN LAYER
+    ├── config/brain.json                       # Master PAT credentials
+    ├── memory-vault/                           # General user preferences
+    └── memory-derived/                         # Ephemeral caches
+
+/Users/greg/Github/total-recall/                <-- LOCAL PROJECT BRAIN LAYER
+└── .agent/skills/total-recall/
+    ├── memory-vault/                           # Project-specific facts
+    └── memory-derived/                         # Unified project-local compiled index
+```
+
+### Cascade Precedence Rules:
+1. **Local Dominance**: If a memory node with the same `slug` exists in both the global vault and the project vault, the **project vault version overrides the global node** on compilation.
+2. **Category Defaulting**: CLI writes default target layers based on memory taxonomy:
+   - **Global**: `invariants`, `preferences`, and `lore`.
+   - **Project**: `facts`, `concepts`, `patterns`, and `decisions`.
+3. **Drift Detection**: The `drift-detector.mjs` continuously validates compiled `graph-index.jsonl` entries against both the local and global canonical `.md` vaults, preventing "ghost records" or missing index entries.
+
+---
+
+## 🌀 The Daemon Loop & Priority Task Scheduler
+
+The background daemon (`dream.mjs`) manages the **Continuous Intelligent Scheduler** ([src/core/scheduler.mjs](file:///Users/greg/Github/total-recall/src/core/scheduler.mjs)) and task execution loops:
+
+### 1. Priority-Driven Queue Mechanics
+Tasks are enqueued dynamically as standard Markdown files (`type: task`) located in your vault's `scheduler/queue/` directory. The scheduler resolves an **Effective Priority** by multiplying the task's base `priority` (10 to 100) by a strictly-regulated **layer weight** (`LAYER_WEIGHTS`), prioritizing critical correctness and active developer guidance over passive exploration:
+- `conscious-enforcement` (Conscious Layer): **1.0** (layer weight)
+- `cutoff-audit` (Training drift validation): **0.9**
+- `system2-deliberation` (Slow System 2 reasoning): **0.8**
+- `memory-maintenance` (Hygiene, decay pruning): **0.6**
+- `skill-engineering` (Scaffolding new capability rules): **0.5**
+- `proactive-research` / `research-acquisition` (Deep crawls): **0.4**
+- `self-evaluation` (Frontier validation benchmarks): **0.3**
+- `exploration` (Speculative tangents): **0.2**
+
+### 2. The Dream Cycle Consolidation
+Every 20 task ticks, the background daemon conducts the **Dream Cycle**:
+- **Light Sleep**: Scans for modified files, updates vector embeddings, and purges/re-indexes caches upon detecting embedding model dimension mismatches.
+- **REM**: Conducts clustering, prunes low-confidence nodes, and decays confidence scores on disused cards.
+- **Deep Sleep**: Re-compiles rules and shims, and writes a daily summary note (`daily/YYYY-MM-DD.md`).
+
+### 3. Continuous Idle Self-Improvement Loops (The Queue is NEVER Empty)
+When the active developer queues are empty, the scheduler **automatically auto-generates idle tasks** to drive continuous optimization at $0 hardware cost. To maintain absolute security and zero local network footprint, it skips internet searches during idle, deploying a round-robin of **clean local strategies**:
+- **Inference Task**: Scans tag clusters of related memory nodes to draw high-level SSSS ontological decisions or flag subtle rule contradictions.
+- **Post-Mortem Task**: Reads and parses the most recent session history log to extract newly observed user preferences, style patterns, and identify subagent skill gaps.
+- **Clarity Review Task**: Selects a random active memory node to audit its JSDoc annotations, title actionability, and Zod schema compliance.
+
+---
+
+## 🏃 hard Task Execution
+
+Pending priority tasks are executed by the **Task Runner** ([src/core/task_runner.mjs](file:///Users/greg/Github/total-recall/src/core/task_runner.mjs)):
+- **State Machine Updates**: Tasks transition transparently through states: `pending` → `in_progress` → `done` or `failed` (logging full exceptions to disk).
+- **Subagent Routing**: Routes tasks to specialized subagents depending on category:
+  - `proactive-research`: Spawns autonomous web crawls and gathers cited research reports (`research.mjs`).
+  - `system2-deliberation`: Executes slow-deliberation inference engines (`inference-engine.mjs`) to consolidate vault data.
+  - `memory-maintenance`: Triggers memory optimization and garbage-collection loops (`optimizer.mjs`).
+
+---
+
+## 🛡️ Sandbox Isolation, Costs, & Firewalls
+
+### 1. Hardened Sandbox Environment
+The sandbox execution layer (`sandbox.mjs`) utilizes strict OS security constraints:
+- **POSIX Namespaces**: Scopes execution boundaries using platform isolation (`sandbox-exec` under macOS, `unshare` under Linux).
+- **Default Offline**: Completely disables outbound network routing unless explicit whitelisted API targets (like the Google Gemini endpoint) are accessed.
+- **Resource Constraints**: Imposes a 512MB RAM utilization threshold and a 60-second execution timeout.
+- **Default Disabled**: Set to `security.yml.sandbox.enabled: false` by default, requiring high-privilege `sandbox:run` token scopes to execute.
+
+### 2. Cost Control watchdog
+- Evaluates cost logging on every subagent dispatch call.
+- Tracks daily and weekly USD costs against threshold limits in `config/budget.yml`.
+- If caps are exceeded, the cost supervisor dynamically aborts outbound dispatches and alerts the developer.
+
+---
+
+## 📂 Consolidated VFS Directory Hierarchy
+
+Total Recall consolidates all data folders under the meta-skill `skills/total-recall/` directory, ensuring simple diff-based git backups and robust security:
+
+```
+.agent/
+└── skills/
+    ├── code-quality/                  # Development skill (not backed up)
+    ├── repo-expert/                   # Development skill (not backed up)
+    └── total-recall/                  # THE BRAIN (Consolidated User Data VFS)
+        ├── SKILL.md                   # Master total-recall capability manifest
+        ├── memory-vault/              # SSSS Canonical Markdown Vault
+        │   ├── invariants/            # priority: absolute → Tier 1 (INSTRUCTIONS.md)
+        │   ├── patterns/              # "Always do X" rules
+        │   ├── anti-patterns/         # "Never do X" rules
+        │   ├── preferences/           # Style preferences
+        │   ├── decisions/             # Architectural history
+        │   ├── concepts/              # High-level domain concepts
+        │   └── facts/                 # Verified facts and evidence
+        ├── memory-derived/            # Ephemeral cached indexes (disposable)
+        │   ├── graph-index.jsonl      # Merged memory index manifest
+        │   ├── embeddings.jsonl       # Vector index coordinates
+        │   └── embeddings-cache.json  # Vector similarity cache
+        ├── memory-inbox/              # Staging area for new nodes
+        │   ├── pending/               # Awaiting ingestion check
+        │   └── conflicts/             # Quarantined rule clashes
+        ├── sessions/                  # Ingested IDE logs and conversation DAGs
+        ├── scheduler/                 # Scheduler metadata
+        │   └── queue/                 # Priority task markdown files
+        ├── config/                    # Config files
+        │   ├── brain.json             # Remote brain URLs and token registries
+        │   ├── budget.yml             # Cost control thresholds
+        │   └── secrets.enc            # AES-256 scrypt-encrypted master API keys
+        ├── logs/                      # JSONL subsystem logs
+        └── .backups/                  # Local encrypted backup snapshots
+
+---
+
+## 💬 Interactive CLI Agent Chat REPL
+
+Total Recall features a native terminal-based chat REPL (`npx total-recall chat`) running [src/cli/chat.mjs](file:///Users/greg/Github/total-recall/src/cli/chat.mjs) that enables direct, conversational access to your active brain kernel from the terminal:
+
+- **CLI-Agent Execution**: Conversation turns are dispatched dynamically to your prioritized **Unified Headless CLI Agents Registry** (`antigravity`, `gemini`, `claude`, `codex`) via `spawnSync`.
+- **Pre-flight Health Routing**: Upon starting, `chat` checks agent binary availability, selecting the highest-priority active subagent found in your `$PATH`.
+- **System Prompts & Context Cascades**: The REPL automatically injects baseline instructions ("Keep responses concise and direct") and formats chat session history sequences cleanly, allowing you to debug rules, steer preferences, and prompt the kernel in real time.
+
+---
+
+## 🔒 Session Security & Token Management
+
+Total Recall implements role-based granular authorization schemas to protect your sovereign brain while maintaining 100% database-free isolation.
+
+### 1. Local Dashboard Session Management (JWT-based)
+For web dashboard access, Total Recall strictly avoids external third-party OAuth provider dependencies (e.g. Google, GitHub, Auth0) to protect your privacy and ensure standalone local operation:
+- **Local Password Authentication**: Submitting a password to `/api/login` verifies it against a high-cost `dashboard.password_hash` (`bcrypt-cost: 12`) stored in `security.yml` and securely mirrored in `secrets.enc`.
+- **Rest-Persistent JWT Cookies**: Upon successful login, the server signs a secure JSON Web Token (`sessionToken`) with a randomly generated 256-bit cryptographic secret (`session-secret`) persisted directly to `config/session-secret` so that logged-in dashboard sessions cleanly survive daemon restarts.
+- **TLS Protection**: The daemon blocks non-secure remote connections, requiring active HTTPS TLS layers (automated via Caddy proxying) for all production traffic.
+
+### 2. Personal Access Token (PAT) Key Lifecycle Manager
+Headless tools, IDE editors, and session Relays authenticate via standard HTTP Bearer headers (`Authorization: Bearer tr_<token>`), managed by the **Keys Lifecycle Manager** ([src/server/keys.mjs](file:///Users/greg/Github/total-recall/src/server/keys.mjs)):
+- **SHA-256 Hash Preservation**: To eliminate credential exposure risk, the server **never writes tokens to disk in plaintext**. It persists only a timing-safe SHA-256 hash (`token_hash`) and a short identifying prefix (`token_prefix`) inside the owner-exclusive `config/keys.jsonl` file (written with `0o600` access modes). Diffs are cleanly git-versioned.
+- **Timing-Attack Protection**: Inbound Bearer PAT tokens are verified using cryptographically secure timing-safe comparisons (`crypto.timingSafeEqual`) on SHA-256 hashes, eliminating timing vector leaks.
+- **Role-Based Granular Scopes**: Validated PAT keys carry granular permission scopes (e.g., `chat:write`, `memory:read`, `sandbox:run`), permitting fine-grained access control boundaries for different editors.
+
+```

package/docs/IDE_INTEGRATION.md

@@ -0,0 +1,112 @@
+# Total Recall — IDE & Agent Integration Guide
+
+Total Recall serves as the core sovereign memory kernel. **Claude Code**, **Cursor**, **Codex CLI**, **Antigravity CLI**, **Aider**, and **VS Code Copilot** act as specialized interfaces on top of it. This guide details how to seamlessly wire each client to the brain.
+
+---
+
+## ⚡ The Integration Workflow
+
+Every IDE and agent reads specific memory instruction files at startup. Total Recall automates this lifecycle:
+
+1. **Watch**: The background relay daemon (`relay.mjs`) automatically watches and captures conversation session traces written by IDE editors.
+2. **Ingest**: Pushes changes to the brain REST API, executing SHA-256 content-hash deduplication.
+3. **Process**: dispatches background post-mortems headlessly to the prioritized **CLI Agents Registry** (e.g. Antigravity CLI, Claude Code) to extract rules, facts, and decisions.
+4. **Compile**: The Dream Cycle compiles your vaults, writing a highly-optimized **5-line progressive disclosure pointer shim** into `INSTRUCTIONS.md`.
+5. **Inject**: Symlinks or projects the compiled memory surface directly into each tool's expected rule file location, ensuring they absorb custom preferences.
+
+---
+
+## 📂 Coexistence & Compatibility Matrix
+
+| Client Editor | Read Target File | Total Recall Action | Relay watched Folder |
+| :--- | :--- | :--- | :--- |
+| **Claude Code** | `CLAUDE.md` | Symlinks `CLAUDE.md` → `INSTRUCTIONS.md` | `~/.claude/projects/*.jsonl` |
+| **Codex CLI** | `AGENTS.md` | Symlinks `AGENTS.md` → `INSTRUCTIONS.md` | `~/.codex/sessions/*.jsonl` |
+| **Antigravity** | `AGENTS.md` | Symlinks `AGENTS.md` → `INSTRUCTIONS.md` | `~/.gemini/antigravity/brain/` |
+| **Cursor** | `.cursor/rules/*.mdc` | Writes `.cursor/rules/total-recall.mdc` | `~/.cursor/projects/*.jsonl` |
+| **Aider** | `.aider.rules.md` | Writes `.aider.rules.md` | Git repo logs |
+| **VS Copilot** | `.github/copilot-instructions.md` | Writes `.github/copilot-instructions.md` | `workspaceStorage/*/chatSessions/` |
+
+---
+
+## 🛠️ Client Configuration Recipes
+
+### 1. Claude Code
+- **Connection Command**:
+  ```bash
+  npx total-recall connect claude-code
+  ```
+- **Coexistence Strategy**: Full compatibility. Claude Code's auto-memories are saved in `~/.claude/memories/` (completely separate). Keep auto-memories enabled; they provide raw context. Total Recall maps `CLAUDE.md` to `INSTRUCTIONS.md`, ensuring all SSSS absolute invariants govern every session.
+
+---
+
+### 2. Antigravity (Google DeepMind SDK)
+- **Connection Command**:
+  ```bash
+  npx total-recall connect antigravity
+  ```
+- **Coexistence Strategy**: Highly complementary. Antigravity reads `AGENTS.md` in your project root, which we symlink to `INSTRUCTIONS.md`. Antigravity's local Knowledge Items (KIs) feed the session watcher logs, which the background daemon digests and promotes into SSSS invariants, updating the pointer shim automatically.
+
+---
+
+### 3. Cursor
+- **Connection Command**:
+  ```bash
+  npx total-recall connect cursor
+  ```
+- **Coexistence Strategy**: Since Cursor has no built-in auto-memory, Total Recall bridges the gap. Connecting writes a modular rule `.cursor/rules/total-recall.mdc` pointing to the rule shim, and the relay daemon captures and digests all your Cursor session logs seamlessly.
+
+---
+
+### 4. VS Code Copilot
+- **Connection Command**:
+  ```bash
+  npx total-recall connect vscode
+  ```
+- **Coexistence Strategy**: Integrates directly. Total Recall projects the compiled rules into `.github/copilot-instructions.md` at the repository root. Scoped local user storage logs are continuously tracked by the relay daemon.
+
+---
+
+### 5. OpenAI Codex
+- **Connection Command**:
+  ```bash
+  npx total-recall connect codex
+  ```
+- **Coexistence Strategy**: Codex reads `AGENTS.md` in the project root, symlinked to our pointer rules. Keep Codex memories enabled; their session traces are picked up by the relay to enrich SSSS.
+
+---
+
+## 🔄 The Self-Improving Feedback Loop
+
+```
+IDE Conversation Sessions (any tool)
+         │
+         ▼ Local Relay Daemon (every 60s)
+Inbound Ingestion API (/api/sessions/ingest)
+         │
+         ▼ SHA-256 Deduplication
+Headless subagent dispatches (Post-Mortem engine)
+         │
+         ▼ In-box pending/ (Quarantine Checks)
+Conflict Steering auto-resolution (Jaccard + SPO)
+         │
+         ▼ memory-vault/ Category Folder
+Background Dream Cycle (Light → REM → Deep sleep)
+         │
+         ▼ compile & rebuild (surface.mjs)
+INSTRUCTIONS.md Compiled Surface Shims Rebuilt
+```
+
+The system is completely **self-improving**: the scheduler automatically creates `skill-engineering` tasks to write new `SKILL.md` rules, `memory-maintenance` tasks to prune disused cards, and `proactive-research` tasks to crawl cited facts in the background.
+
+---
+
+## 🧹 Coexistence Verification
+
+Total Recall never overrides your custom configs. All rules are injected inside the clearly demarcated comment blocks:
+```markdown
+<!-- BEGIN INJECTED MEMORY: do not edit by hand; rebuilt by total-recall surface -->
+...
+<!-- END INJECTED MEMORY -->
+```
+This guarantees that you can safely connect multiple IDEs, Obsidian vaults, and Relays concurrently without risking code loss or compilation lockouts.

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "total-recall-brain",
+  "version": "3.1.0",
+  "description": "Sovereign AI system — database-free, SSSS-powered personal intelligence engine deployable to any POSIX host.",
+  "type": "module",
+  "bin": {
+    "total-recall": "./bin/total-recall.mjs",
+    "antigravity": "./bin/antigravity.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "!src/**/*.spec.mjs",
+    "!src/**/*.test.mjs",
+    "templates/",
+    "scaffold/",
+    "docs/ARCHITECTURE.md",
+    "docs/IDE_INTEGRATION.md",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "exports": {
+    ".": "./src/server/index.mjs",
+    "./fixtures/*": "./fixtures/*",
+    "./src/core/*": "./src/core/*"
+  },
+  "scripts": {
+    "dev": "node src/server/index.mjs",
+    "start": "node src/server/index.mjs",
+    "test": "vitest run",
+    "clean": "rm -rf scratch/* .remember/* *.log"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gregiteen/total-recall.git"
+  },
+  "keywords": [
+    "ai",
+    "sovereign",
+    "ssss",
+    "memory",
+    "local-llm"
+  ],
+  "author": "gregiteen",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/gregiteen/total-recall/issues"
+  },
+  "homepage": "https://github.com/gregiteen/total-recall#readme",
+  "dependencies": {
+    "bcrypt": "^6.0.0",
+    "cookie-parser": "^1.4.7",
+    "cors": "^2.8.6",
+    "express": "^5.2.1",
+    "express-rate-limit": "^8.5.1",
+    "gray-matter": "^4.0.3",
+    "jsonwebtoken": "^9.0.3",
+    "natural": "^8.1.1",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "skills": "^1.5.7",
+    "supertest": "^7.2.2",
+    "vitest": "^4.1.6"
+  },
+  "optionalDependencies": {
+    "playwright": "^1.60.0"
+  }
+}