total-recall-brain

Total Recall — SSSS Sovereign AI OS

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.

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:

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

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

# 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:

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:

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:

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:

npx total-recall uninstall

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.