total-recall-brain 3.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UltraChat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+# Total Recall — SSSS Sovereign AI OS
+
+[![Version](https://img.shields.io/badge/version-3.0.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)
+
+> **A database-free, filesystem-native AI memory layer.** Works in any IDE. Self-hosts on any VM. Costs nothing to store.
+
+Total Recall is the open-source reference implementation of the **SSSS (Structured Semantic Syntax System)** — a specification for storing AI memory, skills, and workflows as plain Markdown files instead of opaque, hosted databases.
+
+```text
+your AI brain = ~/.agent/skills/total-recall/memory-vault/*.md
+```
+
+No database overhead. No vendor lock-in. Your thoughts, on your machine.
+
+---
+
+## 🚀 Choose Your Setup
+
+### 🖥️ 1. IDE Memory Only (2 minutes)
+
+Add persistent, highly contextual memory to **Claude Code**, **Cursor**, **Codex CLI**, or any IDE agent in your active workspace:
+
+```bash
+cd ~/my-project
+npx total-recall init                   # provision global brain and local project VFS shims
+npx total-recall connect claude-code     # symlink CLAUDE.md → INSTRUCTIONS.md
+```
+
+Supported IDEs and surfaces:
+
+| Client Command | Connection Mode | Targeted Projection Target |
+| :--- | :--- | :--- |
+| `npx total-recall connect claude-code` | Symlink | Symlinks `CLAUDE.md` to the compiled instruction surface |
+| `npx total-recall connect codex` | Symlink | Symlinks `AGENTS.md` to the compiled instruction surface |
+| `npx total-recall connect antigravity` | Symlink | Symlinks `AGENTS.md` to the compiled instruction surface |
+| `npx total-recall connect gemini` | Symlink | Symlinks `GEMINI.md` to the compiled instruction surface |
+| `npx total-recall connect cursor` | File Projection | Writes/updates `.cursor/rules/total-recall.mdc` with frontmatter rules |
+| `npx total-recall connect aider` | File Projection | Writes/updates `.aider.rules.md` file rules |
+
+> [!NOTE]
+> **Non-Destructive Integration:**
+> Your existing custom rules are **never overwritten**. Total Recall operates exclusively inside the clearly-marked comment bounds:  
+> `<!-- BEGIN INJECTED MEMORY: do not edit by hand; rebuilt by total-recall surface -->`  
+> `...`  
+> `<!-- END INJECTED MEMORY -->`
+
+---
+
+### 🧠 2. Full Sovereign Brain VM (10 minutes)
+
+Deploy the full autonomous stack — a secure OpenAI-compatible REST server, dynamic React dashboard, continuous Dream Cycle daemon, and local session relays — on your own VM.
+
+**Prerequisites:**
+- A standard Linux or macOS server/workstation.
+- Node.js ≥ 20.
+- A primary API Key (e.g. `GOOGLE_API_KEY` for high-speed Google `gemini-embedding-2` vectors, featuring OpenAI fallback).
+
+```bash
+# Start the interactive configuration wizard:
+npx total-recall init
+```
+
+The interactive wizard provisions the configuration, registers authorized Personal Access Tokens (PATs), configures secure Caddy reverse-proxying, and prompts you to choose your **Selectable UI Deployment Location**:
+
+| Mode | Target URL | Primary Target |
+| :--- | :--- | :--- |
+| **Local Bind** | `http://127.0.0.1:3000` | Local operations. Binds strictly to your loopback interface. |
+| **Quick Tunnel** | `https://*.trycloudflare.com` | Spawns a background Cloudflare tunnel for zero-configuration public URL access. |
+| **Named Tunnel** | `https://your-tunnel.domain.com` | Hooks up securely to a pre-registered Cloudflare tunnel daemon. |
+| **Custom Domain** | `https://your-domain.com` | Hooks up to your public DNS, reverse-proxied and secured by Caddy TLS. |
+
+To start the server daemon, run:
+```bash
+npm start
+```
+*Vite automatically installs and builds the beautiful Glassmorphic React SPA on first boot, serving the dashboard dynamically.*
+
+---
+
+### 📔 3. Obsidian Integration
+
+Visualize your entire memory vault, rules network, and daily logs directly inside Obsidian with native backlinks and graphs:
+
+```bash
+npx total-recall connect obsidian
+```
+*Auto-detects your vault path on macOS (or pass `--vault ~/path/to/vault` on Linux/other), symlinking your memory vault and installing interactive Dataview dashboard trackers.*
+
+---
+
+### 💬 4. UltraChat Integration
+
+UltraChat integrates securely with your brain via our OpenAI-compatible chat API, injecting active memory instructions into system prompts on the fly:
+
+```bash
+npx total-recall connect ultrachat --brain https://your-server.com --token YOUR_PAT
+```
+*Generates the OpenAI-compatible configuration parameters (baseURL, model, token auth header).*
+
+---
+
+## 🧠 Dual-Layer Brain Architecture
+
+Total Recall partitions your sovereign brain memory into two virtual layers:
+
+```
+                      ┌────────────────────────┐
+                      │      GLOBAL LAYER      │
+                      │  ~/.agent/skills/tr/   │
+                      └───────────┬────────────┘
+                                  │
+                                  ▼ Overridden by
+                      ┌────────────────────────┐
+                      │     PROJECT LAYER      │
+                      │  <repo>/.agent/skills/ │
+                      └────────────────────────┘
+```
+
+1. **Global Layer** (`~/.agent/skills/total-recall/`): Contains global user preferences, master API keys, global logs, and the baseline identity context (`SOUL.md`, `USER.md`).
+2. **Project Layer** (`<repo>/.agent/skills/total-recall/`): Contains local repository facts, project-specific habits, and specialized research agendas.
+
+*When compiling rules or searching, project-level nodes take precedence and override global nodes on slug collisions. CLI operations like `remember`, `recall`, `research`, `backup`, and `restore` accept `--global` and `--project` flags to steer memories to the right layer.*
+
+---
+
+## ⚡ CLI Command Reference
+
+| Command | Description |
+| :--- | :--- |
+| `npx total-recall init` | Initialize the global or local project VFS memory schemas. |
+| `npx total-recall connect <client>` | Wire a local IDE, Obsidian vault, or UltraChat client to your brain. |
+| `npx total-recall deploy` | Configure startup services, Caddy proxy servers, and platform auto-starts. |
+| `npx total-recall compile` | Rebuild `INSTRUCTIONS.md` from merged global & project memory nodes. |
+| `npx total-recall dream` | Trigger a manual Dream Cycle (GC, pattern extraction, decay consolidation). |
+| `npx total-recall lint` | Validate vault nodes against the SSSS v2 frontmatter Zod schema. |
+| `npx total-recall backup` | Create password-encrypted tarballs, push git backups, or sync Obsidian. |
+| `npx total-recall restore <file>` | Restore your sovereign VFS from an encrypted tarball backup. |
+| `npx total-recall status` | Show brain health summary, connected client registries, and daemon status. |
+| `npx total-recall generate-pat` | Provision granular, label-based Personal Access Tokens (PATs) for auth. |
+| `npx total-recall daemon` | Manage the background Dream Cycle daemon (start / stop / status). |
+| `npx total-recall relay` | Manage background local session-sync relays watching IDE log files. |
+| `npx total-recall config` | Read or update system settings, Allowed Origins, or USD budget caps dynamically. |
+| `npx total-recall skill` | Search, install, security-audit, and remove packages from the skills.sh registry. |
+| `npx total-recall uninstall` | Completely stop background services and wipe Total Recall from the system. |
+| `npx total-recall friction` | Inspect watchdog telemetry logs to identify workflow latency bottlenecks. |
+
+---
+
+## 🔒 Security, Sandboxing, & Safety
+
+- **硬 Hardened VM Sandbox:** All subagent script executions run inside an isolated vm sandbox environment (`sandbox.mjs`) featuring POSIX namespace restrictions, strict memory/CPU bounds, and a command execution whitelist. The sandbox is **disabled by default** (`security.yml.sandbox.enabled: false`) for maximum security.
+- **Cost Watchdog & Limits:** Daily and weekly maximum cost thresholds (`config/budget.yml`) are enforced dynamically via a cost supervisor in `runtime.mjs` that instantly suspends subagent dispatches if budget caps are exceeded.
+- **OWASP-aligned scrypt Security:** Master credentials and API keys are AES-256-GCM encrypted under `secrets.enc` with OWASP-aligned scrypt key derivation.
+- **Privacy Redactions:** Memory nodes marked with `privacy: local_only` are automatically stripped before any external API dispatches or reasoning agent calls.
+
+---
+
+## 🧹 Service Uninstallation
+
+To cleanly stop background daemons, unload platform agents (macOS launchd plists / Linux systemd services), remove symlink shims from all workspaces, and purge global configs:
+
+```bash
+npx total-recall uninstall
+```
+> [!IMPORTANT]
+> **Safety First:**
+> The uninstaller automatically detects version-controlled files, **preserving** local workspace `.agent/skills/` and `.agent/memory-vault/` directories inside active git project repositories to ensure you never lose custom rules and memories.
+
+---
+
+*Sovereign. Database-free. Yours.*

package/bin/antigravity.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const args = process.argv.slice(2);
+let prompt = '';
+let outputJson = false;
+let requestedModel = process.env.TR_CLI_MODEL || 'default';
+
+if (args.includes('-h') || args.includes('--help')) {
+  console.log(`
+Antigravity CLI Agent Wrapper — Headless Zero-Dependency Cognitive Agent
+
+Usage:
+  antigravity [options] [prompt]
+  antigravity -p "prompt"
+
+Options:
+  -p, --prompt    The text prompt to generate content for
+  -m, --model     Gemini API model identifier or alias (default: default / gemini-3.5-flash)
+                  Supported aliases:
+                    - default / gemini / flash / gemini-flash -> dynamically resolves best Flash model
+                    - pro / gemini-pro / 3.1-pro             -> dynamically resolves best Pro model
+  -o, --json      Output dynamic JSON response payload (choices: stream/json/default)
+  --json          Output dynamic JSON response payload
+  -h, --help      Show this help information
+
+Examples:
+  antigravity "Say hello"
+  antigravity -p "Write an essay about AI" -m pro
+  antigravity -p "Get system stats" --json
+`);
+  process.exit(0);
+}
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '-p' || args[i] === '--prompt') {
+    prompt = args[i + 1] || '';
+    i++;
+  } else if (args[i] === '-o' && args[i + 1] === 'json') {
+    outputJson = true;
+    i++;
+  } else if (args[i] === '--json') {
+    outputJson = true;
+  } else if (args[i] === '-m' || args[i] === '--model') {
+    requestedModel = args[i + 1] || requestedModel;
+    i++;
+  }
+}
+
+if (!prompt && args.length > 0) {
+  prompt = args[args.length - 1];
+}
+
+if (!prompt) {
+  console.error('Error: No prompt provided. Use -p "prompt"');
+  process.exit(1);
+}
+
+// Robust fallback to load GOOGLE_API_KEY from .env files when executed standalone
+if (!process.env.GOOGLE_API_KEY) {
+  try {
+    let dir = process.cwd();
+    while (dir !== path.dirname(dir)) {
+      const envPath = path.join(dir, '.env');
+      if (fs.existsSync(envPath)) {
+        const content = fs.readFileSync(envPath, 'utf8');
+        for (const line of content.split('\n')) {
+          const match = line.match(/^\s*GOOGLE_API_KEY\s*=\s*(["']?)(.*?)\1\s*$/);
+          if (match) {
+            process.env.GOOGLE_API_KEY = match[2];
+            break;
+          }
+        }
+      }
+      if (process.env.GOOGLE_API_KEY) break;
+      dir = path.dirname(dir);
+    }
+  } catch {
+    // Silent ignore
+  }
+}
+
+const apiKey = process.env.GOOGLE_API_KEY;
+if (!apiKey) {
+  console.error('Error: GOOGLE_API_KEY environment variable is not configured.');
+  process.exit(1);
+}
+
+// Resolve the model dynamically from the API registry based on the category/alias selected
+async function resolveGenerativeModel(selectedModel) {
+  const aliases = {
+    gemini: 'flash',
+    default: 'flash',
+    flash: 'flash',
+    'gemini-flash': 'flash',
+    '3.5-flash': 'flash',
+    pro: 'pro',
+    'gemini-pro': 'pro',
+    '3.1-pro': 'pro'
+  };
+
+  const category = aliases[selectedModel];
+  if (!category) {
+    // If it's a full model string, use it directly
+    return selectedModel;
+  }
+
+  try {
+    const res = await fetch(`https://generativelanguage.googleapis.com/v1beta/models?key=${apiKey}`, {
+      signal: AbortSignal.timeout(5000)
+    });
+    if (res.ok) {
+      const data = await res.json();
+      const models = data.models || [];
+      
+      if (category === 'pro') {
+        const proPreferences = [
+          'gemini-3.1-pro-preview',
+          'gemini-2.5-pro',
+          'gemini-1.5-pro',
+          'gemini-pro-latest'
+        ];
+        for (const p of proPreferences) {
+          if (models.some(m => m.name === `models/${p}`)) {
+            return p;
+          }
+        }
+      } else {
+        const flashPreferences = [
+          'gemini-3.5-flash',
+          'gemini-3.1-flash-lite',
+          'gemini-2.5-flash',
+          'gemini-2.0-flash-lite',
+          'gemini-flash-latest'
+        ];
+        for (const p of flashPreferences) {
+          if (models.some(m => m.name === `models/${p}`)) {
+            return p;
+          }
+        }
+      }
+    }
+  } catch {
+    // Silent failover to hardcoded default targets
+  }
+
+  // Ultimate fallback
+  return category === 'pro' ? 'gemini-3.1-pro-preview' : 'gemini-3.5-flash';
+}
+
+async function main() {
+  try {
+    const resolvedModel = await resolveGenerativeModel(requestedModel);
+    const url = `https://generativelanguage.googleapis.com/v1beta/models/${resolvedModel}:generateContent?key=${apiKey}`;
+
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        contents: [{
+          parts: [{ text: prompt }]
+        }]
+      })
+    });
+
+    if (!res.ok) {
+      const errText = await res.text();
+      throw new Error(`Gemini API returned status ${res.status}: ${errText}`);
+    }
+
+    const data = await res.json();
+    const text = data.candidates?.[0]?.content?.parts?.[0]?.text || '';
+
+    // Save usage data for token monitoring/budget safety
+    try {
+      const promptTokens = data.usageMetadata?.promptTokenCount || 0;
+      const candidatesTokens = data.usageMetadata?.candidatesTokenCount || 0;
+      if (promptTokens > 0 || candidatesTokens > 0) {
+        const tmpDir = path.join(os.homedir(), '.gemini', 'tmp', 'antigravity', 'chats');
+        if (!fs.existsSync(tmpDir)) {
+          fs.mkdirSync(tmpDir, { recursive: true });
+        }
+        const usageLine = JSON.stringify({
+          timestamp: new Date().toISOString(),
+          tokens: {
+            input: promptTokens,
+            output: candidatesTokens
+          }
+        });
+        fs.appendFileSync(path.join(tmpDir, 'usage.jsonl'), usageLine + '\n', 'utf8');
+      }
+    } catch {
+      // Silent ignore
+    }
+
+    if (outputJson) {
+      console.log(JSON.stringify({ response: text }));
+    } else {
+      console.log(text);
+    }
+  } catch (err) {
+    console.error('Error calling Gemini API:', err.message);
+    process.exit(1);
+  }
+}
+
+main();

package/bin/init.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+import os from 'os';
+import path from 'path';
+import fs from 'fs';
+
+const HOME = os.homedir();
+const AGENT_DIR = path.join(HOME, '.agent');
+const BRAIN_DIR = path.join(AGENT_DIR, 'skills', 'total-recall');
+
+const directories = [
+  path.join(AGENT_DIR, 'skills'),
+  path.join(BRAIN_DIR, 'memory-vault', 'invariants'),
+  path.join(BRAIN_DIR, 'memory-vault', 'patterns'),
+  path.join(BRAIN_DIR, 'memory-vault', 'anti-patterns'),
+  path.join(BRAIN_DIR, 'memory-vault', 'preferences'),
+  path.join(BRAIN_DIR, 'memory-vault', 'decisions'),
+  path.join(BRAIN_DIR, 'memory-vault', 'concepts'),
+  path.join(BRAIN_DIR, 'memory-derived'),
+  path.join(BRAIN_DIR, 'memory-inbox', 'pending'),
+  path.join(BRAIN_DIR, 'memory-inbox', 'conflicts'),
+  path.join(BRAIN_DIR, 'sessions'),
+];
+
+console.log('🚀 Initializing Total Recall SSSS Memory Vault...\n');
+
+directories.forEach(dir => {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+    console.log(`✅ Created: ${dir}`);
+  } else {
+    console.log(`👍 Exists:  ${dir}`);
+  }
+});
+
+console.log('\n🎉 SSSS Vault initialization complete. No database required.');

package/bin/oci-sniper.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+
+# Oracle Cloud Instance Auto-Provisioning Sniper
+# This script will continuously attempt to create an Ampere A1 instance
+# until capacity is available in your region.
+
+# --- CONFIGURATION (Replace these with your exact OCIDs from the Oracle Console) ---
+COMPARTMENT_ID="ocid1.tenancy.oc1..aaaaaaaabjccfnrjtwyf2shaww62vxpavualyuxr277uhgd66yyxjw2wjg2a"
+SUBNET_ID="ocid1.subnet.oc1.phx.aaaaaaaatpvwsqwnxzbmacl4nwfqrqlky4br25iv2muyk36b4oe7vmfzfcia"
+IMAGE_ID="ocid1.image.oc1.phx.aaaaaaaaza5inn2bm77iz5yqaobyqi6x5k2w7buo4tbekiijkuluetyr3dkq"
+SSH_KEY_FILE="$HOME/.ssh/id_ed25519.pub"
+AVAILABILITY_DOMAIN="JJIu:PHX-AD-1" # Switched to AD-1 since AD-2 was out of capacity
+SHAPE="VM.Standard.A1.Flex"
+OCPUS=4
+MEMORY=24
+# -----------------------------------------------------------------------------------
+
+if ! command -v ~/bin/oci &> /dev/null && ! command -v oci &> /dev/null; then
+    echo "OCI CLI is not installed."
+    echo "1. Install it via Homebrew: brew install oci-cli"
+    echo "2. Authenticate: ~/bin/oci setup config"
+    exit 1
+fi
+
+# Determine correct oci binary path
+OCI_BIN="oci"
+if [ -x "$HOME/bin/oci" ]; then
+    OCI_BIN="$HOME/bin/oci"
+fi
+
+echo "Starting OCI Sniper... Target: $SHAPE ($OCPUS OCPUs, $MEMORY GB RAM) in $AVAILABILITY_DOMAIN"
+
+while true; do
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] Attempting to provision instance..."
+    
+    # Capture both stdout and stderr, and the exit code
+    OUTPUT=$($OCI_BIN compute instance launch \
+        --compartment-id "$COMPARTMENT_ID" \
+        --availability-domain "$AVAILABILITY_DOMAIN" \
+        --shape "$SHAPE" \
+        --shape-config "{\"memoryInGBs\": $MEMORY, \"ocpus\": $OCPUS}" \
+        --subnet-id "$SUBNET_ID" \
+        --image-id "$IMAGE_ID" \
+        --ssh-authorized-keys-file "$SSH_KEY_FILE" \
+        --display-name "Total-Recall-Brain" \
+        --assign-public-ip true 2>&1)
+    
+    EXIT_CODE=$?
+
+    if [ $EXIT_CODE -eq 0 ]; then
+        echo "✅ SUCCESS! Instance provisioned."
+        echo "$OUTPUT"
+        
+        # Trigger macOS Desktop Notification
+        osascript -e 'display notification "Your 24GB Oracle instance has been successfully provisioned!" with title "Total Recall Sniper"'
+        if [ -f "node .agent/skills/notifications/scripts/notify.mjs" ]; then
+            node .agent/skills/notifications/scripts/notify.mjs "Total Recall Sniper" "Your 24GB Oracle instance has been successfully provisioned! Go to your dashboard to get the IP."
+        fi
+
+        echo "Sniper terminating. Go check your Oracle Dashboard!"
+        exit 0
+    else
+        # It failed. Let's just print the error and wait 60 seconds to try again.
+        echo "❌ Provisioning failed (Oracle API is busy or out of capacity). Retrying in 60 seconds..."
+        # If they want to see the error they can check the terminal output:
+        echo "$OUTPUT" | grep -E '"message"|"code"|Exception' | head -n 3
+        sleep 60
+    fi
+done