total-recall-brain 3.1.0

package/scaffold/.agent/skills/total-recall/SKILL.md

@@ -0,0 +1,195 @@
+---
+type: skill
+name: total-recall
+description: "Use this skill as the master guide to understand the entire Total Recall Sovereign AI OS setup, VFS topologies, SSSS protocol, CLI parameter reference, troubleshooting, and automated upstream repository sync. MANDATORY: Read this file before attempting major setup modifications or diagnoses."
+---
+
+# Total Recall — Master Agent Skill (REST API First)
+
+Welcome to the master control skill for the **Total Recall Sovereign AI OS**. > [!NOTE]
+> **Total Recall Architecture:**
+> The Total Recall memory kernel runs as a standalone REST service. Agents interact with the memory vault, perform semantic searches, and compile rules directly using lightweight, filesystem-native REST API calls via standard shell `curl` commands.
+
+---
+
+## 🎯 WHEN TO USE THIS SKILL
+
+You MUST actively reference and apply this skill under the following specific runtime scenarios:
+
+### 1. When the user establishes a rule, preference, or correction
+*   **Trigger**: Whenever the user corrects your behavior, shares a coding style, defines an architectural pattern, or establishes a preference you must remember.
+*   **Action**: Autonomously create a new SSSS v2 memory node under `.agent/memory-vault/` and compile the vault.
+
+### 2. When referencing invariants, preferences, and corrections (Intrinsically Known Rules)
+*   **⚠️ MANDATORY**: The compiled instruction files (like `INSTRUCTIONS.md`, `GEMINI.md`, `AGENTS.md`, etc.) contain the **entirety** of active invariants, preferences, and behavior corrections (rules/directives).
+*   **Action**: You **intrinsically know these rules** because they are injected directly into your active prompt/instruction context. You **MUST NEVER** execute manual filesystem searches (grep, find) or REST API/curl queries to discover or check these basic rules.
+
+### 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.
+
+### 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.
+*   **Must NOT Trigger**: Do NOT use background research for quick searches of simple APIs, common code snippets, or basic web-related docs. Standard models have active web search capabilities that should be used for these quick, on-demand reference lookups.
+*   **Action**: Autonomously queue the topic to the background research agenda using the `/api/research` REST API POST endpoint to let the daemon build a high-confidence vault node.
+
+### 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`.
+
+### 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.
+*   **Action**: Refer to the active diagnostics manual within this skill to heal the local runtime.
+
+---
+
+## ⚡ 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.
+
+### 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.
+
+### 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:
+`<!-- BEGIN INJECTED MEMORY: do not edit by hand; rebuilt by total-recall surface -->`
+...
+`<!-- END INJECTED MEMORY -->`
+
+### 4. Upstream Skill Synchronization
+Keep local skill definitions and invariant files updated by executing the sync runner:
+```bash
+node .agent/skills/total-recall/scripts/sync-repo.mjs
+```
+This utility fetches standard skill and invariant definitions from the upstream repository, merges them non-destructively preserving custom user nodes, and auto-recompiles the workspace.
+
+### 5. Premium Browser Setup Wizard Onboarding
+For first-time system installations, migrations, or editor reconnections, launch the visual onboarding setup wizard:
+```bash
+npx total-recall deploy --ui
+```
+This spins up a secure local Express server (port 3000, increments dynamically if occupied) and automatically launches the graphical installation dashboard in your macOS or Linux browser, providing:
+*   **Deployment Scoping**: Seamless visual provisioning for local machine brains, remote network computers (SSH), rented GPU cloud servers (Vast.ai), or custom VPS droplets.
+*   **Credential Restoration**: Automatically parses, protects, and restores AES-encrypted API tokens and bcrypt cost-12 dashboard passwords from `.agent/secrets.enc` so you never lose credentials.
+*   **Automated SSL & Tunnels**: Automatically deploys free, encrypted Cloudflare Quick Tunnels (`*.trycloudflare.com`) or permanent Zero Trust domains over secure HTTPS/Caddy TLS.
+*   **Omni-Channel Integration Checklists**: Multi-select and configure your active editors (Claude Code, Cursor, Codex, Gemini, VS Code, Obsidian) with live terminal logs in the browser.
+
+---
+
+## 🌐 DIRECT REST API REFERENCE
+
+All requests to the Total Recall REST API must include the Bearer token in the `Authorization` header.
+
+*   **Active Bearer PAT Token**: `<YOUR_PAT_TOKEN>` (Retrieve dynamically from process.env.TR_PAT or read .agent/config/brain.json)
+*   **Base URL**: `<YOUR_BRAIN_URL>` (Retrieve from process.env.TR_BRAIN or read .agent/config/brain.json; default: http://localhost:3000)
+
+### Endpoint Reference & curl Templates
+
+| Method | Route | Description |
+|---|---|---|
+| `GET` | `/health` | Check system health (vault count, embeddings, CLI agents availability) |
+| `GET` | `/api/vault/status` | Vault stats summary |
+| `GET` | `/api/memory` | List all SSSS memory nodes |
+| `GET` | `/api/memory/:slug` | Fetch a single SSSS memory node by its slug |
+| `POST` | `/api/memory` | Create or update (upsert) a memory node |
+| `POST` | `/api/memory/search/semantic` | Perform vector semantic search using local dense embeddings |
+| `POST` | `/api/research` | Queue a topic for the background research daemon |
+| `GET` | `/api/research` | Retrieve/search active research agenda & queue |
+| `POST` | `/api/vault/compile` | Recompile derived index caches and rule surfaces |
+| `DELETE` | `/api/memory/:slug` | Archive a memory node |
+
+#### 1. Check System Health
+```bash
+curl -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+  <YOUR_BRAIN_URL>/health
+```
+
+#### 2. Perform Vector Semantic Search (Use this for all concept lookup requests)
+```bash
+curl -X POST \
+  -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "your search query here", "top_k": 5}' \
+  <YOUR_BRAIN_URL>/api/memory/search/semantic
+```
+
+#### 3. Fetch a Specific Memory Node
+```bash
+curl -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+  <YOUR_BRAIN_URL>/api/memory/slug-name
+```
+
+#### 4. List All Memory Nodes
+```bash
+curl -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+  "<YOUR_BRAIN_URL>/api/memory"
+```
+
+#### 5. Create or Update a Memory Node
+```bash
+curl -X POST \
+  -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "slug": "atomic-writes",
+    "category": "facts",
+    "title": "Always write files atomically",
+    "status": "active",
+    "confidence": 0.95,
+    "importance": 4,
+    "modality": "must",
+    "content": "Always write files atomically by creating a temporary file first and renaming it to prevent partial file writes."
+  }' \
+  <YOUR_BRAIN_URL>/api/memory
+```
+
+#### 6. Trigger Surface Recompilation (Run this after adding, editing, or deleting memory files)
+```bash
+curl -X POST \
+  -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+  <YOUR_BRAIN_URL>/api/vault/compile
+```
+
+#### 7. Archive a Memory Node
+```bash
+curl -X DELETE \
+  -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+  <YOUR_BRAIN_URL>/api/memory/slug-name
+```
+
+#### 8. Queue Autonomous Research
+```bash
+curl -X POST \
+  -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{"topic": "Next.js 15 routing models", "priority": "high", "notes": "Analyze layout models"}' \
+  <YOUR_BRAIN_URL>/api/research
+```
+
+#### 9. Retrieve and Search/Filter Research Projects
+Query the background research queue, optionally filtering by status (`pending`, `in_progress`, `done`, `failed`) or searching the `topic` and `notes` fields with a dynamic query string.
+```bash
+# Retrieve entire research queue
+curl -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+  "<YOUR_BRAIN_URL>/api/research"
+
+# Filter research projects by status
+curl -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+  "<YOUR_BRAIN_URL>/api/research?status=pending"
+
+# Dynamically search research projects by topic/notes query
+curl -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+  "<YOUR_BRAIN_URL>/api/research?query=Next.js"
+```
+
+---
+
+<!-- BEGIN INJECTED MEMORY: do not edit by hand; rebuilt by total-recall surface -->
+<!-- @route: tfidf, generated_at: 2026-05-21T03:34:14.837Z -->
+
+<!-- END INJECTED MEMORY -->

package/scaffold/.agent/skills/total-recall/evals/evals.json

@@ -0,0 +1,20 @@
+[
+  {
+    "id": "total-recall-eval-1",
+    "description": "Ensure total-recall SKILL.md exists and contains SSSS name frontmatter",
+    "command": "test -f .agent/skills/total-recall/SKILL.md && grep -q 'name: total-recall' .agent/skills/total-recall/SKILL.md",
+    "expected_exit_code": 0
+  },
+  {
+    "id": "total-recall-eval-2",
+    "description": "Ensure all core total-recall references are present",
+    "command": "test -f .agent/skills/total-recall/references/architecture-reference.md && test -f .agent/skills/total-recall/references/ssss-reference.md && test -f .agent/skills/total-recall/references/cli-reference.md && test -f .agent/skills/total-recall/references/troubleshooting.md",
+    "expected_exit_code": 0
+  },
+  {
+    "id": "total-recall-eval-3",
+    "description": "Ensure upstream sync script is syntactically valid and executes without crash",
+    "command": "node --check .agent/skills/total-recall/scripts/sync-repo.mjs",
+    "expected_exit_code": 0
+  }
+]

package/scaffold/.agent/skills/total-recall/memory-vault/concepts/cli-help-reference.md

@@ -0,0 +1,145 @@
+---
+type: memory
+slug: cli-help-reference
+category: concepts
+title: "Total Recall Command & Architecture Help Reference"
+schema_version: 2
+status: active
+confidence: 1.0
+importance: 5
+priority: high
+modality: descriptive
+tags: [cli, help, commands, VFS, integrations, scheduler, daemon, budget, sandbox, watchdog]
+created: 2026-05-25T00:51:00Z
+updated: 2026-05-25T00:56:00Z
+---
+
+# Total Recall Command & Architecture Help Reference
+
+To guarantee perfect system awareness and eliminate unexpected retrieval latency, this semantic node documents the entire layout, core commands, internal features, and the interactive help subsystems of the **Total Recall Sovereign OS**.
+
+---
+
+## 1. Local VFS Directory Layout
+Total Recall operates completely database-free, utilizing a Markdown-first, grey-matter frontmatter structure. The local VFS resides in `.agent/skills/total-recall/` (global: `~/.agent/skills/total-recall/`, project-layered: `<repo-root>/.agent/skills/total-recall/`):
+
+* **`memory-vault/`**: Categories of persistent semantic nodes:
+  * `invariants/`: Absolute rules and protocols (e.g. `operating-instructions.md`).
+  * `preferences/`: Communication styles and personalization templates.
+  * `facts/`: General factual nodes.
+  * `concepts/`: High-level domain architectural rules.
+  * `decisions/`: Historical project decisions.
+  * `patterns/` & `anti-patterns/`: Desired vs forbidden coding behaviors.
+  * `lore/`: Core project history.
+* **`sessions/`**: Synced chat transcripts stored as JSONL (`<hash>.jsonl`).
+* **`scheduler/queue/`**: Task nodes (`.md`) executed asynchronously by the background task manager.
+* **`memory-derived/`**: Cached indices and compiled graph canvas visualizers (`graph-index.jsonl`, `canvas.json`).
+* **`config/`**:
+  * `agents.yml`: Headless CLI agent registry (`antigravity`, `gemini`, `claude`, `codex`).
+  * `secrets.enc`: Secure, GPG-encrypted API keys and dashboard credentials.
+  * `security.yml`: Password hashes and network authorization settings.
+  * `budget.yml`: Cost-control settings for daily and weekly dollar caps.
+
+---
+
+## 2. Platform Core Features & Hardening
+
+### 🪙 Budget Supervisor & Cost Control
+* **File:** `.agent/skills/total-recall/config/budget.yml`
+* **Features:** Enforces strict daily (`daily_cap_usd`, default $5.00) and weekly (`weekly_cap_usd`, default $25.00) dollar limits.
+* **Hardening:** Spawning processes pass through a pre-flight gateway in `src/core/runtime.mjs`. If execution logs reveal that budget limits are breached, the gate blocks subsequent agent dispatches, sends a system alert, and enters protective hibernation.
+
+### 🛡️ Watchdog Circuit Breaker & Quarantining
+* **Features:** Continually monitors background daemon loops and log streams in real time.
+* **Hardening:** If a critical subsystem (such as the sandboxed compiler or an API integration) fails $\geq 3$ consecutive times, the watchdog automatically trips the circuit breaker and quarantines the failing subsystem to protect local directory structures.
+
+### 🗃️ Hardened Local VFS Sandbox
+* **Features:** Hardened gateway that isolates execution environments for untrusted Node.js/JavaScript script blocks.
+* **Command:** `POST /api/sandbox`
+* **Hardening:** Restricts shell execution, network permissions, and isolates path routing to within local repository boundaries to prevent directory traversal or system manipulation.
+
+### 🔍 Drift Detector & Index Reconciliation
+* **Features:** Compares the active state of the canonical vault directory against derived index tables.
+* **Command:** `npx total-recall compile --check` (or `rebuild --check`)
+* **Hardening:** Detects index drift, missing vector records, or out-of-sync wikilinks, allowing automated repair.
+
+### 🔄 Ingest Fabric & Session Sync Relay
+* **Features:** Seamless background synchronization for local IDE chats (Claude Code, Copilot, Cursor).
+* **Command:** `npx total-recall relay start`
+* **Details:** Watches active IDE workspaces and safely ships raw conversation logs to your remote brain, deduplicating entries via content SHA-256 fingerprint hashing.
+
+---
+
+## 3. Interactive Offline Help System
+To query documentation, VFS specifications, or CLI usage instantly without file hunting, you can run:
+
+```bash
+# General help utility and subcommands menu
+npx total-recall help
+
+# Print a specific subcommand's description, options, and examples
+npx total-recall help <command> (e.g., npx total-recall help connect)
+
+# Query system architecture specifications
+npx total-recall help architecture
+
+# Query SSSS syntax rules and schemas
+npx total-recall help ssss
+```
+
+* **Programmatic AI Retrieval:** AI agents can query the help system using the `--json` or `-j` flag:
+  `npx total-recall help <command> --json`
+  This returns structured JSON specs outlining the command's flags, client modes, and examples, ensuring full operational precision.
+
+---
+
+## 4. Core Command Reference
+
+### `init`
+* **Purpose:** Bootstrap VFS into a project.
+* **Usage:** `npx total-recall init`
+
+### `connect`
+* **Purpose:** Link Cursor, Claude Code, Codex, Windsurf, Aider, or Obsidian to your brain.
+* **Usage:** `npx total-recall connect <client> [options]`
+
+### `deploy`
+* **Purpose:** Provision a server stack (Ollama, Caddy, Cloudflare tunnels, etc.).
+* **Usage:** `npx total-recall deploy`
+
+### `compile` (alias: `rebuild`)
+* **Purpose:** Rebuild system projections, canvas canvases, and compiled instructions shims (`INSTRUCTIONS.md`).
+* **Usage:** `npx total-recall compile`
+
+### `dream`
+* **Purpose:** Trigger REM sleep consolidation (deduplication, confidence score decay).
+* **Usage:** `npx total-recall dream`
+
+### `research`
+* **Purpose:** Manage autonomous background research queue tasks.
+* **Usage:** `npx total-recall research <list|add|show|report|cancel>`
+
+### `daemon`
+* **Purpose:** Manage background scheduler task daemon.
+* **Usage:** `npx total-recall daemon <start|stop|status>`
+
+### `relay`
+* **Purpose:** Manage local IDE session synchronizer.
+* **Usage:** `npx total-recall relay <start|stop|status|once>`
+
+### `uninstall`
+* **Purpose:** Clean, git-safe system cleanup.
+* **Usage:** `npx total-recall uninstall`
+
+### `config`
+* **Purpose:** Dynamically read, write, and toggle UI, security, and budget settings (acting as the command-line control harness).
+* **Usage:**
+  - `npx total-recall config get [key]` - Read the active value of a specific setting, or list all configured settings.
+  - `npx total-recall config set <key> <value>` - Cast, validate, and write a setting to `security.yml` or `budget.yml`.
+
+---
+
+## 5. Dynamic Integrations
+You can instantly deploy any custom REST API as a first-class CLI subcommand by adding an integration Markdown node:
+* **Path:** `.agent/skills/total-recall/integrations/<serviceName>.md`
+* **Routing:** Unrecognized CLI commands automatically look up this path. If found, the integration dispatcher binds your terminal arguments dynamically, signs headers with env credentials, and executes the request instantly.

package/scaffold/.agent/skills/total-recall/memory-vault/invariants/operating-instructions.md

@@ -0,0 +1,75 @@
+---
+type: memory
+slug: operating-instructions
+category: invariants
+title: "Total Recall Core Operating Protocol"
+schema_version: 2
+status: active
+confidence: 1.0
+importance: 5
+priority: absolute
+immutable: true
+modality: must
+subject: agent
+predicate: operate
+object: memory_system
+created: 2026-05-01T00:00:00Z
+updated: 2026-05-15T00:00:00Z
+last_accessed: 2026-05-15T00:00:00Z
+source:
+  type: scaffold
+  session_id: scaffold-seed
+  agent: total-recall
+  evidence_count: 1
+supersedes: []
+superseded_by: null
+contradicts: []
+tags: [ssss, sovereignty, memory, protocol]
+related: []
+routes_to_skills: [ssss]
+sentiment_polarity: directive_must
+sentiment_target: memory_system
+decay:
+  half_life_days: 365
+  access_count: 1
+---
+
+# Total Recall Operating Protocol
+
+You are operating within the **Total Recall Sovereign OS**. Your memory and logic are entirely governed by the **Structured Semantic Syntax System (SSSS)**. There is no external database. The filesystem is your brain.
+
+## ⚠️ CLI-First Mandate (Absolute Rule)
+**ALWAYS use the Total Recall CLI for ALL memory operations.** The CLI handles schema validation, semantic indexing, conflict detection, and auto-compilation. Manual file operations bypass all of these safeguards.
+- **Searching memory**: `npx total-recall recall "<query>"` — NEVER manually grep, find, or read files in the memory vault.
+- **Writing memory**: `npx total-recall remember <category> "<content>"` — NEVER manually create or edit vault files with file writing tools.
+- **Compiling**: The CLI auto-compiles after writes. If you need a manual recompile, use `npx total-recall compile`.
+- Reading `.agent/skills/` SKILL.md files with filesystem tools is fine — those are skill instructions, not memory nodes.
+
+## 1. Memory Architecture
+- You do not use external databases or third-party persistence stores.
+- Every memory, rule, concept, or workflow is a standalone Markdown (`.md`) file with YAML frontmatter, managed exclusively through the CLI.
+
+## 2. Reading Memory
+- Your immediate context is injected automatically via compiled instruction surfaces.
+- If you need deeper knowledge on a specific domain, read the `SKILL.md` files located in `.agent/skills/`.
+- To search for facts, decisions, patterns, or any stored knowledge, use `npx total-recall recall "<query>"`.
+
+## 3. Writing Memory
+When you learn a new pattern, receive a correction, or establish a new rule, you must autonomously save it using the CLI:
+- Use `npx total-recall remember <category> "<content>"` with appropriate flags (`--importance`, `--priority`, `--modality`, `--tags`).
+- The CLI validates the SSSS schema, writes the node, and auto-compiles surfaces. You do not need to read the SSSS spec or manually construct YAML frontmatter.
+
+## 4. Compiling the Vault
+- The `remember` CLI auto-compiles after every write. No manual step is needed.
+- If you need to force a recompile (e.g., after external edits), run `npx total-recall compile`.
+- If the compile process flags a conflict, resolve it using `npx total-recall resolve`.
+
+## 5. Execution Mandate
+You must operate autonomously. Do not ask for permission to save memories or compile the vault. If you observe a pattern or receive a correction, use the CLI to save and compile it immediately.
+
+## 6. Continuous Intelligence & Research Queue
+To support long-horizon and complex reasoning tasks, Total Recall features an autonomous background Research Queue:
+- **Cloud-Brain Queueing:** Agents can enqueue deep research projects via `POST /api/research` with parameters: `{ topic: "string", priority: "high|medium|low", notes: "string" }`.
+- **Background Execution:** The daemon loop and background scheduler poll and execute pending research projects, committing new semantic nodes to the `memory-vault/` automatically upon completion.
+- **Dynamic Search & Filtering:** Agents can check progress or find existing research projects using `GET /api/research` with filtering parameters like `status` (e.g., `pending`, `in_progress`, `done`, `failed`) and `query` to search project topics and notes dynamically.
+- **Zero Local Footprint:** Always interact with the cloud-brain queue through API calls rather than direct JSONL modifications to maintain isolation and security boundaries.

package/scaffold/.agent/skills/total-recall/memory-vault/preferences/always-websearch-gap.md

@@ -0,0 +1,16 @@
+---
+slug: always-websearch-gap
+category: preferences
+title: "Always Perform Web Search for Cutoff Gap"
+status: active
+priority: absolute
+modality: must
+---
+
+# Always Perform Web Search for Cutoff Gap
+
+When encountering any technical topic, library version, pricing structure, service features, or API changes that are obviously within or past the knowledge cutoff gap (2025/2026+), the agent MUST:
+
+1. **Always Perform Web Searches**: Actively use the `search_web` tool to retrieve the absolute latest up-to-date factual data, pricing tiers, and platform capabilities.
+2. **Never Guess or Assume**: Do not rely on pre-cutoff weights or make assumptions about active cloud services, PaaS tiers, or local-first setups.
+3. **Verify Before Recommending**: Retrieve fresh information before presenting recommendations or trade-offs to the user.

package/scaffold/.agent/skills/total-recall/memory-vault/preferences/topic-research-sop.md

@@ -0,0 +1,17 @@
+---
+slug: topic-research-sop
+category: preferences
+title: "Standard Operating Procedure for Topic Research"
+status: active
+priority: absolute
+modality: must
+---
+
+# Standard Operating Procedure for Topic Research
+
+When the user requests research on a topic, the agent MUST automatically set the brain to become an expert in that topic. The agent MUST:
+
+1. **Queue Research Instantly**: Queue the topic in the background research daemon (`POST /api/research`) to autonomously crawl and acquire deep mastery.
+2. **Maintain a Single Living Scratch Document**: Keep exactly one living document under `.agent/scratch/` and update it continuously as new findings arise. Do NOT create multiple different files or reports.
+3. **Ensure Full Searchability**: Autonomously write memory nodes to the brain and execute index compilation (`POST /api/vault/compile`) so the knowledge is fully searchable.
+4. **Operate Completely Autonomously**: Perform these steps without asking the user for review, instructions, or permission. The agent must proceed silently and automatically until the user explicitly asks for status or results.

package/scaffold/.agent/skills/total-recall/references/api-reference.md

@@ -0,0 +1,187 @@
+# Total Recall REST API Reference
+
+LLM agents securely communicate with the memory kernel using standard HTTP calls via shell execution (e.g. `curl`).
+
+---
+
+## 🔒 Authentication & Headers
+
+All requests to the Total Recall REST API must include the Bearer token in the `Authorization` header.
+
+*   **Header**: `Authorization: Bearer <PAT>`
+*   **Active Bearer PAT Token**: `<YOUR_PAT_TOKEN>`
+*   **Base URL (Remote Tunnel)**: `<YOUR_BRAIN_URL>`
+*   **Base URL (Local)**: `http://localhost:3000`
+
+---
+
+## 🧭 Endpoint Reference
+
+### 1. Check System Health
+Returns the status of the vault, embeddings index, and LLM reachability.
+
+*   **Method / Route**: `GET /health`
+*   **Example curl**:
+    ```bash
+    curl -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+      <YOUR_BRAIN_URL>/health
+    ```
+*   **Response Format (`application/json`)**:
+    ```json
+    {
+      "status": "healthy",
+      "version": "3.0.0",
+      "uptime_seconds": 123,
+      "timestamp": "2026-05-21T03:50:00.000Z",
+      "disk": {
+        "free": 85899345920,
+        "total": 107374182400
+      },
+      "cli_agents": ["antigravity", "gemini", "claude", "codex"],
+      "daemon": "running",
+      "emergency_alerts": null,
+      "vfs": {
+        "exists": true,
+        "skill_exists": true,
+        "path": "/Users/greg/.agent"
+      }
+    }
+    ```
+
+---
+
+### 2. Vault Status Summary
+Provides a high-level summary of the semantic vault.
+
+*   **Method / Route**: `GET /api/vault/status`
+*   **Example curl**:
+    ```bash
+    curl -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+      <YOUR_BRAIN_URL>/api/vault/status
+    ```
+
+---
+
+### 3. List Vault Nodes
+Returns a list of all SSSS memory nodes. Supports query filtering by `q` (text search), `category`, or `tag`.
+
+*   **Method / Route**: `GET /api/memory`
+*   **Query Parameters**:
+    *   `q` (optional): Plain-text keyword search
+    *   `category` (optional): `facts` / `patterns` / `concepts` / `preferences` / `corrections` / `invariants`
+    *   `tag` (optional): Freeform tag filter
+*   **Example curl**:
+    ```bash
+    curl -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+      "<YOUR_BRAIN_URL>/api/memory?category=invariants"
+    ```
+
+---
+
+### 4. Fetch a Memory Node
+Retrieves a single SSSS memory node by its unique slug.
+
+*   **Method / Route**: `GET /api/memory/:slug`
+*   **Example curl**:
+    ```bash
+    curl -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+      <YOUR_BRAIN_URL>/api/memory/chocolate-brownies
+    ```
+
+---
+
+### 5. Create a Memory Node (Upsert)
+Saves a memory node directly to the local filesystem vault. Accepts both `"content"` (preferred) and `"body"` (fallback) for the markdown text body payload.
+
+*   **Method / Route**: `POST /api/memory`
+*   **Headers**: `Content-Type: application/json`
+*   **Example curl**:
+    ```bash
+    curl -X POST \
+      -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+      -H "Content-Type: application/json" \
+      -d '{
+        "slug": "atomic-writes",
+        "category": "patterns",
+        "title": "Always write files atomically",
+        "status": "active",
+        "confidence": 0.95,
+        "importance": 4,
+        "modality": "must",
+        "content": "Always write files atomically by creating a temporary file first and renaming it to prevent partial file writes."
+      }' \
+      <YOUR_BRAIN_URL>/api/memory
+    ```
+
+---
+
+### 6. Semantic Vector Search
+Performs a high-performance vector search across all memory nodes and session history.
+
+*   **Method / Route**: `POST /api/memory/search/semantic`
+*   **Headers**: `Content-Type: application/json`
+*   **Request Body Fields**:
+    *   `query` (string): The search query or semantic concept.
+    *   `top_k` (number, optional): Max results to return. Defaults to `5`.
+*   **Example curl**:
+    ```bash
+    curl -X POST \
+      -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+      -H "Content-Type: application/json" \
+      -d '{ "query": "baking brownies", "top_k": 3 }' \
+      <YOUR_BRAIN_URL>/api/memory/search/semantic
+    ```
+
+---
+
+### 7. Queue Autonomous Research
+Queues a complex topic to the background research daemon.
+
+*   **Method / Route**: `POST /api/research`
+*   **Headers**: `Content-Type: application/json`
+*   **Example curl**:
+    ```bash
+    curl -X POST \
+      -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+      -H "Content-Type: application/json" \
+      -d '{ "topic": "Next.js 15 Server Actions best practices", "priority": "high" }' \
+      <YOUR_BRAIN_URL>/api/research
+    ```
+
+---
+
+### 8. List Research Agenda
+Retrieves all topics currently on the background research agenda with their statuses.
+
+*   **Method / Route**: `GET /api/research`
+*   **Example curl**:
+    ```bash
+    curl -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+      <YOUR_BRAIN_URL>/api/research
+    ```
+
+---
+
+### 9. Trigger Surface Recompilation
+Triggers a manual rebuild of derived index caches, surface instructions, and routes.
+
+*   **Method / Route**: `POST /api/vault/compile`
+*   **Example curl**:
+    ```bash
+    curl -X POST \
+      -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+      <YOUR_BRAIN_URL>/api/vault/compile
+    ```
+
+---
+
+### 10. Archive or Delete a Memory Node
+Deletes a memory node from the local filesystem vault.
+
+*   **Method / Route**: `DELETE /api/memory/:slug`
+*   **Example curl**:
+    ```bash
+    curl -X DELETE \
+      -H "Authorization: Bearer <YOUR_PAT_TOKEN>" \
+      <YOUR_BRAIN_URL>/api/memory/atomic-writes
+    ```