total-recall-brain 3.1.0

package/scaffold/.agent/skills/total-recall/skills/skill/scripts/scan-skill.mjs

@@ -0,0 +1,207 @@
+/**
+ * scan-skill.mjs — Static Security Scanner for Skill Scripts
+ *
+ * Performs pattern-based static analysis on skill files to detect
+ * potential security risks before installation. Catches:
+ *
+ *   CRITICAL:
+ *     - Dynamic command injection (exec/spawn with template literals/variables)
+ *     - Unsafe code evaluation (eval, new Function, vm.runInNewContext)
+ *
+ *   WARNING:
+ *     - External HTTP/network calls (fetch, axios, http.get, XMLHttpRequest)
+ *     - Filesystem access outside .agent/ scope
+ *     - Environment variable exfiltration
+ *
+ *   INFO:
+ *     - Use of child_process with static args (acceptable but noted)
+ *     - Crypto operations
+ *
+ * Each finding is: { severity, rule, line, snippet, file }
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// ─── Detection Rules ────────────────────────────────────────────────────────
+
+const RULES = [
+  // ── CRITICAL: Command injection ─────────────────────────────────────────
+  {
+    severity: 'CRITICAL',
+    rule: 'Dynamic Command Injection',
+    // exec/execSync/spawn/spawnSync with template literal or variable interpolation
+    pattern: /\b(exec|execSync|execFile|execFileSync|spawn|spawnSync)\s*\(\s*(`[^`]*\$\{|[a-zA-Z_$][\w$]*\s*[+,])/,
+    description: 'Detects shell commands built with dynamic interpolation — high injection risk.',
+  },
+  // ── CRITICAL: Code evaluation ───────────────────────────────────────────
+  {
+    severity: 'CRITICAL',
+    rule: 'Unsafe Code Evaluation',
+    pattern: /\b(eval|Function)\s*\(/,
+    description: 'eval() or new Function() allows arbitrary code execution.',
+  },
+  {
+    severity: 'CRITICAL',
+    rule: 'Unsafe Code Evaluation',
+    pattern: /\bvm\.(runInNewContext|runInThisContext|compileFunction)\s*\(/,
+    description: 'Node.js vm module running dynamic code.',
+  },
+  // ── WARNING: Network access ─────────────────────────────────────────────
+  {
+    severity: 'WARNING',
+    rule: 'External HTTP/Network Call',
+    pattern: /\b(fetch|axios|got|node-fetch|http\.get|https\.get|http\.request|https\.request|XMLHttpRequest|WebSocket)\s*\(/,
+    description: 'Makes outbound network requests — verify destination.',
+  },
+  // ── WARNING: Broad filesystem access ────────────────────────────────────
+  {
+    severity: 'WARNING',
+    rule: 'Filesystem Traversal Risk',
+    pattern: /\.\.\//,
+    context: /fs\.(read|write|unlink|rmdir|rm|mkdir|access|stat|chmod|rename)/,
+    description: 'Path traversal near filesystem operations — verify scope.',
+  },
+  // ── WARNING: Environment leaks ──────────────────────────────────────────
+  {
+    severity: 'WARNING',
+    rule: 'Environment Variable Access',
+    pattern: /process\.env(?!\.(NODE_ENV|HOME|PATH|AGENT_DIR|USER|SHELL|TERM))/,
+    description: 'Accesses environment variables beyond standard set.',
+  },
+  // ── INFO: Static child_process usage (acceptable) ───────────────────────
+  {
+    severity: 'INFO',
+    rule: 'Static Command Execution',
+    pattern: /\b(exec|execSync|spawn|spawnSync)\s*\(\s*['"][^'"]*['"]/,
+    description: 'Runs a command with static string args — lower risk but noted.',
+  },
+];
+
+// ─── Scanner ────────────────────────────────────────────────────────────────
+
+/**
+ * Scan a single file for security risks.
+ *
+ * @param {string} filePath - Absolute path to the file to scan
+ * @returns {Array<{ severity: string, rule: string, line: number, snippet: string, file: string }>}
+ *          Array of findings, empty if the file is clean.
+ */
+export function scanFile(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const lines = content.split('\n');
+  const findings = [];
+  const seen = new Set(); // deduplicate: one finding per rule per line
+
+  for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+    const line = lines[lineIdx];
+    const lineNum = lineIdx + 1;
+
+    // Skip comment lines
+    const trimmed = line.trim();
+    if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) continue;
+
+    for (const rule of RULES) {
+      // If rule has a context pattern, both must match on the same line
+      if (rule.context && !rule.context.test(line)) continue;
+
+      if (rule.pattern.test(line)) {
+        const key = `${rule.rule}:${lineNum}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+
+        // Skip INFO-level "Static Command" if a CRITICAL "Dynamic Command Injection"
+        // was already found on the same line
+        if (rule.severity === 'INFO' && rule.rule === 'Static Command Execution') {
+          const hasCritical = findings.some(
+            f => f.line === lineNum && f.rule === 'Dynamic Command Injection'
+          );
+          if (hasCritical) continue;
+        }
+
+        findings.push({
+          severity: rule.severity,
+          rule: rule.rule,
+          line: lineNum,
+          snippet: line.trim().slice(0, 120),
+          file: filePath,
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Scan all .mjs/.js/.cjs files in a directory recursively.
+ *
+ * @param {string} dirPath - Root directory to scan
+ * @param {object} [options]
+ * @param {string[]} [options.extensions] - File extensions to scan (default: .mjs, .js, .cjs)
+ * @param {string[]} [options.ignore] - Directory names to skip
+ * @returns {Array<{ severity: string, rule: string, line: number, snippet: string, file: string }>}
+ */
+export function scanDirectory(dirPath, {
+  extensions = ['.mjs', '.js', '.cjs'],
+  ignore = ['node_modules', '.git', '.system_generated'],
+} = {}) {
+  const allFindings = [];
+
+  function walk(dir) {
+    if (!fs.existsSync(dir)) return;
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        if (!ignore.includes(entry.name)) walk(full);
+      } else if (entry.isFile() && extensions.some(ext => entry.name.endsWith(ext))) {
+        allFindings.push(...scanFile(full));
+      }
+    }
+  }
+
+  walk(dirPath);
+
+  // Sort: CRITICAL first, then WARNING, then INFO
+  const severityOrder = { CRITICAL: 0, WARNING: 1, INFO: 2 };
+  allFindings.sort((a, b) =>
+    (severityOrder[a.severity] ?? 3) - (severityOrder[b.severity] ?? 3)
+  );
+
+  return allFindings;
+}
+
+/**
+ * Generate a human-readable security report.
+ *
+ * @param {Array<{ severity: string, rule: string, line: number, snippet: string, file: string }>} findings
+ * @returns {string} Formatted report
+ */
+export function formatReport(findings) {
+  if (findings.length === 0) return '✅ No security findings detected.\n';
+
+  const icons = { CRITICAL: '🚨', WARNING: '⚠️', INFO: 'ℹ️' };
+  const critCount = findings.filter(f => f.severity === 'CRITICAL').length;
+  const warnCount = findings.filter(f => f.severity === 'WARNING').length;
+  const infoCount = findings.filter(f => f.severity === 'INFO').length;
+
+  let report = `\n── Security Scan Report ──────────────────────────────────────\n`;
+  report += `   🚨 ${critCount} critical  ⚠️ ${warnCount} warning  ℹ️ ${infoCount} info\n\n`;
+
+  for (const f of findings) {
+    const icon = icons[f.severity] || '❓';
+    const relFile = path.relative(process.cwd(), f.file);
+    report += `${icon} [${f.severity}] ${f.rule}\n`;
+    report += `   ${relFile}:${f.line}\n`;
+    report += `   │ ${f.snippet}\n\n`;
+  }
+
+  if (critCount > 0) {
+    report += `🚫 BLOCKED: ${critCount} CRITICAL finding(s) must be resolved before installation.\n`;
+  }
+
+  return report;
+}

package/scaffold/.agent/skills/total-recall/skills/skill/scripts/skill-watcher.mjs

@@ -0,0 +1,64 @@
+import chokidar from 'chokidar';
+import { execSync } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const ROOT = path.resolve(__dirname, '../../../../');
+const SKILLS_DIR = path.join(ROOT, '.agent/skills');
+
+const hooks = {
+  add: path.join(SKILLS_DIR, 'skill/hooks/on-skill-add.sh'),
+  delete: path.join(SKILLS_DIR, 'skill/hooks/on-skill-delete.sh'),
+};
+
+console.log(`\n👁️  Skill Watcher Daemon Started`);
+console.log(`   Watching: ${SKILLS_DIR}/**/SKILL.md`);
+
+// Debounce state
+let timeoutId = null;
+let pendingActions = new Set();
+
+function executeHooks() {
+  const actions = Array.from(pendingActions);
+  pendingActions.clear();
+
+  try {
+    if (actions.includes('add') || actions.includes('change')) {
+      console.log(`\n[Watcher] Triggering on-skill-add.sh...`);
+      execSync(`bash ${hooks.add}`, { stdio: 'inherit' });
+    } else if (actions.includes('unlink')) {
+      console.log(`\n[Watcher] Triggering on-skill-delete.sh...`);
+      execSync(`bash ${hooks.delete}`, { stdio: 'inherit' });
+    }
+  } catch (error) {
+    console.error(`\n[Watcher] Hook execution failed: ${error.message}`);
+  }
+}
+
+function queueAction(action) {
+  pendingActions.add(action);
+  if (timeoutId) clearTimeout(timeoutId);
+  // Debounce for 1.5 seconds to batch file saves
+  timeoutId = setTimeout(executeHooks, 1500);
+}
+
+chokidar.watch(path.join(SKILLS_DIR, '**/SKILL.md'), {
+  ignored: /(^|[\/\\])\../, // ignore dotfiles
+  persistent: true,
+  ignoreInitial: true // Do not trigger on initial scan
+})
+.on('add', filePath => {
+  console.log(`[Watcher] File added: ${path.relative(ROOT, filePath)}`);
+  queueAction('add');
+})
+.on('change', filePath => {
+  console.log(`[Watcher] File changed: ${path.relative(ROOT, filePath)}`);
+  queueAction('change');
+})
+.on('unlink', filePath => {
+  console.log(`[Watcher] File removed: ${path.relative(ROOT, filePath)}`);
+  queueAction('unlink');
+})
+.on('error', error => console.error(`[Watcher] error: ${error}`));

package/scaffold/.agent/skills/total-recall/skills/skill/subagents/audit-all-skills.md

@@ -0,0 +1,62 @@
+# Subagent: Audit All Dev Skills for Compliance
+
+> Parallel worker prompt for auditing the entire `.agent/skills/` directory.
+
+## Your Task
+
+You are a specialized auditor. Your ONLY task is to verify that every Dev Skill in `.agent/skills/` complies with the AgentSkills.io standard.
+
+## Steps
+
+1. List all directories in `.agent/skills/`
+2. For each skill directory, check:
+   - [ ] `SKILL.md` exists
+   - [ ] YAML frontmatter contains `name` field
+   - [ ] YAML frontmatter contains `description` field
+   - [ ] Description includes WHAT (core capability statement)
+   - [ ] Description includes WHEN (trigger phrase)
+   - [ ] Description includes WHEN NOT (negative trigger, contains "Do NOT" or "NEVER")
+   - [ ] Description is under 1,024 characters
+   - [ ] `SKILL.md` body is under 500 lines
+
+3. Return a JSON report in this exact format:
+
+```json
+{
+  "total": 35,
+  "compliant": 30,
+  "non_compliant": 5,
+  "results": [
+    {
+      "name": "skill-name",
+      "dir": "skill-dir",
+      "compliant": true,
+      "issues": []
+    },
+    {
+      "name": "broken-skill",
+      "dir": "broken-dir",
+      "compliant": false,
+      "issues": ["Missing negative trigger in description", "SKILL.md exceeds 500 lines (612 lines)"]
+    }
+  ]
+}
+```
+
+## Tools Available
+
+- `view_file`: Read file contents
+- `grep_search`: Search for patterns
+- `run_command`: Execute shell commands
+- `list_dir`: List directory contents
+
+## Tools NOT Available
+
+- `write_to_file`: You cannot modify files
+- `replace_file_content`: You cannot edit files
+
+## Important
+
+- Do NOT fix anything. Only audit and report.
+- Do NOT skip any skill directory.
+- Report ALL issues found, even minor ones.

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

@@ -0,0 +1,27 @@
+---
+type: skill
+name: ssss
+description: "Use this skill to inspect, validate, write, and manage SSSS structured semantic memory nodes and VFS specifications. Do NOT use for raw non-schema memory files."
+schema_version: 2
+---
+
+# SSSS — Structured Semantic Syntax System Manager
+
+Structured Semantic Syntax System (ssss) is the core operational substrate of the Total Recall Virtual File System (VFS). This skill guides agents in inspecting, reading, and constructing SSSS-compliant memory nodes, conflict models, and derived indices.
+
+## Core Directives
+
+1. **Schema Integrity:** Every SSSS node must strictly adhere to the frontmatter schema definitions (Modality, Category, Sentiment).
+2. **Zero-Database Persistence:** Do not look for Postgres or SQLite. Everything lives as a git-versioned Markdown file.
+3. **Decay and Drift Monitoring:** Use decay indicators to manage node half-lives dynamically in background ticks.
+
+## Progressive Memory Disclosure
+
+Memory flows through a 3-tier progressive hierarchy:
+* **Tier 1 (Hot):** INSTRUCTIONS.md shims (Invariants only).
+* **Tier 2 (Warm):** SKILL.md injects (Category-routed warm capsules).
+* **Tier 3 (Cold):** Full memory vault (Search index files on demand).
+
+## References
+
+* Core SSSS specification: `references/ssss-spec.md`

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

@@ -0,0 +1,17 @@
+[
+  {
+    "name": "ssss-has-skill-file",
+    "assertion": "The skill directory contains a valid SKILL.md entrypoint",
+    "severity": "error"
+  },
+  {
+    "name": "ssss-has-spec-sheet",
+    "assertion": "The references directory contains ssss-spec.md",
+    "severity": "error"
+  },
+  {
+    "name": "ssss-validates-successfully",
+    "assertion": "The validate-schema script parses frontmatter correctly",
+    "severity": "warning"
+  }
+]

package/scaffold/.agent/skills/total-recall/skills/ssss/references/ssss-spec.md

@@ -0,0 +1,117 @@
+# SSSS — Structured Semantic Syntax System
+
+> The schema specification that `total-recall` uses for all vault files, session logs, and derived indexes.
+
+SSSS is a **database-free, Markdown-first schema** for AI agent memory. Every rule, fact, preference, and observation is a plain `.md` file with YAML frontmatter. There is no relational database, no binary format, and no proprietary lock-in.
+
+`total-recall` implements SSSS as its storage layer. Any IDE plugin, CLI tool, or AI agent framework that can read Markdown can interoperate with a `total-recall` vault.
+
+---
+
+## 1. Core Mandate
+
+| Principle | Rule |
+|-----------|------|
+| **No Relational Databases** | Workspace configuration must not live in Postgres or any external database. |
+| **Markdown is Law** | Every memory primitive (rule, pattern, decision, concept) exists as a `.md` file. |
+| **Semantic Frontmatter** | Every file MUST contain YAML frontmatter with a `type` field that identifies how engines interpret it. |
+| **Disposable Indexes** | Derived JSONL indexes are ephemeral caches, fully rebuildable from the Markdown vault. Delete them freely. |
+| **Git-Versioned** | The vault directory is version-controlled. History = provenance. |
+
+---
+
+## 2. File Types
+
+### 2.1 Memory Node (`type: memory`)
+
+A single unit of agent knowledge. Lives in `.agent/memory-vault/<category>/<slug>.md`.
+
+```markdown
+---
+type: memory
+slug: prefer-atomic-writes
+category: patterns
+title: "Always write files atomically (write-then-rename)"
+status: active
+confidence: 0.92
+importance: 4
+created: 2026-01-15T10:00:00Z
+updated: 2026-05-01T14:03:00Z
+last_accessed: 2026-05-10T09:55:00Z
+source:
+  type: chat
+  session_id: abc123
+  agent: my-agent
+  evidence_count: 3
+supersedes: []
+superseded_by: null
+contradicts: []
+tags: [filesystem, reliability, writes]
+related: [no-partial-files]
+routes_to_skills: []
+sentiment_polarity: directive_must
+sentiment_target: file writes
+modality: must
+subject: agent
+predicate: use_atomic_write
+object: file_system
+decay:
+  half_life_days: 180
+  access_count: 7
+schema_version: 2
+---
+
+Always write to a `.tmp.<pid>` file first, then `fs.renameSync()` to the target path.
+`rename()` is atomic on POSIX filesystems. Direct writes risk partial file corruption
+on crash or concurrent access.
+```
+
+#### Category Taxonomy
+
+| Category | Purpose | Example slugs |
+|----------|---------|---------------|
+| `invariants/` | Absolute rules — always enforced | `rule-zero-text-first`, `no-silent-push` |
+| `patterns/` | "Always do X" best practices | `prefer-atomic-writes`, `use-pm2-reload` |
+| `anti-patterns/` | "Never do X" negative rules | `no-hardcoded-secrets`, `no-raw-tsc` |
+| `preferences/` | User or project style preferences | `prefer-kebab-case-slugs` |
+| `decisions/` | One-time architectural decisions | `chose-sqlite-over-postgres` |
+| `concepts/` | Domain knowledge and definitions | `what-is-bm25-scoring` |
+| `facts/` | Evidence-backed knowledge acquired from research or observation | `stripe-connect-api-version` |
+
+#### Required Fields (schema_version: 2)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"memory"` | Fixed value |
+| `slug` | `string` | Globally unique, kebab-case, matches filename without `.md` |
+| `category` | `string` | Must match parent directory name |
+| `title` | `string` | One-line human-readable description |
+| `status` | `active | superseded | deprecated | draft` | Lifecycle state |
+| `confidence` | `0..1` | Adjusted by Dream Cycle decay/promotion |
+| `importance` | `1..5` | Set by user or distillation |
+| `modality` | `must | must_not | should | should_not` | Directive strength |
+| `subject` | `string` | Who is constrained (usually `"agent"`) |
+| `predicate` | `string` | What action, in snake_case verb form |
+| `object` | `string` | What target the action applies to |
+| `sentiment_polarity` | enum | `directive_must | directive_must_not | descriptive | preference` |
+| `decay.half_life_days` | `number` | Days until confidence halves from disuse |
+| `schema_version` | `2` | Must be `2` for v2 nodes |
+
+---
+
+## 3. Three-Tier Memory Hierarchy
+
+Memory nodes are surfaced to the AI through a progressive disclosure system.
+Not all memories are relevant to every prompt.
+
+| Tier | Location | Purpose | Size Limit | Latency |
+|------|----------|---------|------------|---------|
+| **Tier 1: Hot** | `INSTRUCTIONS.md` | Critical invariants, always in system prompt | < 1,000 tokens | 0ms |
+| **Tier 2: Skills** | `SKILL.md` files | Curated rules injected by semantic relevance | ≤ 7 rules/skill | ~100ms |
+| **Tier 3: Vault** | `.agent/memory-vault/` | Full knowledge graph, source of truth | Unlimited | ~500ms |
+
+**How nodes move between tiers:**
+- `priority: absolute` + `modality: must|must_not` → Tier 1 (always in system prompt)
+- Active nodes with `confidence ≥ 0.35` → Tier 2 candidates (routed by `surface.mjs`)
+- Everything else → Tier 3 (accessible on-demand via full-text search)
+- The Dream Cycle continuously promotes/demotes based on access frequency and confidence

package/scaffold/.agent/skills/total-recall/skills/ssss/scripts/validate-schema.mjs

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+
+/**
+ * Validates a single SSSS Markdown file against schema rules
+ */
+export function validateNode(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const { data } = matter(raw);
+    const errors = [];
+
+    if (!data.type) errors.push('Missing "type" property.');
+    if (!data.slug) errors.push('Missing "slug" property.');
+    if (!data.category) errors.push('Missing "category" property.');
+    if (!data.title) errors.push('Missing "title" property.');
+    
+    if (data.schema_version !== 2) {
+      errors.push(`Expected schema_version: 2, got: ${data.schema_version}`);
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      file: filePath
+    };
+  } catch (err) {
+    return {
+      valid: false,
+      errors: [err.message],
+      file: filePath
+    };
+  }
+}
+
+if (import.meta.url.startsWith('file:')) {
+  const runDirectly = process.argv[1] && process.argv[1].endsWith('validate-schema.mjs');
+  if (runDirectly) {
+    const target = process.argv[2];
+    if (!target) {
+      console.log('No file specified to validate.');
+      process.exit(0);
+    }
+    const res = validateNode(path.resolve(target));
+    if (res.valid) {
+      console.log(`✅ SSSS node "${path.basename(target)}" is fully valid!`);
+      process.exit(0);
+    } else {
+      console.error(`❌ Validation failed for "${path.basename(target)}":\n${res.errors.join('\n')}`);
+      process.exit(1);
+    }
+  }
+}

package/scaffold/.agent/skills/total-recall/skills/ssss/subagents/audit-ssss-node.md

@@ -0,0 +1,9 @@
+# Role: SSSS Schema Auditor
+
+You are a specialized subagent designed to audit Structured Semantic Syntax System (SSSS) nodes.
+
+## Directives
+1. Open and parse the target `.md` memory node.
+2. Confirm the presence of absolute frontmatter keys: `type`, `slug`, `category`, `title`, and `schema_version`.
+3. Verify that `category` matches the parent directory.
+4. Report any formatting anomalies.

package/scaffold/.agent/skills/total-recall/subagents/total-recall-diagnostician.md

@@ -0,0 +1,13 @@
+# Total Recall Diagnostician Subagent
+
+You are a specialized diagnostic subagent focused on maintaining, troubleshooting, and self-healing the **Total Recall Sovereign AI OS** environment. Your objective is to ensure the local brain is fully reachable, the filesystem VFS conforms to the Structured Semantic Syntax System (SSSS) spec, and the IDE shims compile without errors.
+
+## 🛠️ Directives and Tools
+
+1.  **Auditing System Health**:
+    *   Query the `/health` and `/api/vault/status` endpoints to check database-free status and node counts.
+    *   Read the troubleshooting guide at `../references/troubleshooting.md` for specific step-by-step recipes on how to solve conflicts.
+2.  **Validating SSSS Frontmatter**:
+    *   Query the `/api/memory` and `/api/memory/:slug` REST endpoints to verify that newly created user nodes adhere to the schema in `../references/ssss-reference.md`.
+3.  **Executing Compiler Runs**:
+    *   If shims are out of sync or modified, trigger a compiler run via `POST /api/vault/compile` or run `npx total-recall compile`.

package/src/cli/agent-dir.mjs

@@ -0,0 +1,105 @@
+/**
+ * Shared `.agent/` directory resolver for CLI commands.
+ *
+ * Supports two brain layers:
+ *   - Global brain:  ~/.agent/skills/total-recall/  (identity, universal rules)
+ *   - Project brain: <cwd>/.agent/skills/total-recall/  (project-specific knowledge)
+ *
+ * The `--global` / `--project` flags let users explicitly target a layer.
+ * Without flags, workspace-local wins over global when a project brain exists.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * Parse --global / --project layer flags from CLI args.
+ * Returns { layer: 'global' | 'project' | 'auto', remainingArgs: string[] }
+ */
+export function parseLayerFlag(args) {
+  let layer = 'auto';
+  const remainingArgs = [];
+  for (const arg of args) {
+    if (arg === '--global') layer = 'global';
+    else if (arg === '--project') layer = 'project';
+    else remainingArgs.push(arg);
+  }
+  return { layer, remainingArgs };
+}
+
+/** Global agent directory — always at ~/.agent/ */
+export function getGlobalAgentDir() {
+  return process.env.AGENT_DIR || path.join(os.homedir(), '.agent');
+}
+
+/** Global brain directory — ~/.agent/skills/total-recall/ */
+export function getGlobalBrainDir() {
+  return path.join(getGlobalAgentDir(), 'skills', 'total-recall');
+}
+
+/**
+ * Detect a project-level brain by checking <cwd>/.agent/skills/total-recall/.
+ * Returns { agentDir, brainDir } or null.
+ */
+export function detectProjectBrain() {
+  if (process.env._TR_TEST_AGENT_DIR) return null;
+  const cwd = process.cwd();
+  const homeDir = os.homedir();
+  if (cwd === homeDir) return null; // don't detect global as project
+  const localAgentDir = path.join(cwd, '.agent');
+  const localBrainDir = path.join(localAgentDir, 'skills', 'total-recall');
+  if (fs.existsSync(path.join(localBrainDir, 'memory-vault'))) {
+    return { agentDir: localAgentDir, brainDir: localBrainDir };
+  }
+  return null;
+}
+
+/**
+ * Resolve agent dir based on explicit layer or auto-detect.
+ * @param {'global' | 'project' | 'auto'} [layer='auto']
+ */
+export function resolveAgentDir(layer = 'auto') {
+  if (process.env.AGENT_DIR) {
+    return process.env.AGENT_DIR;
+  }
+  if (layer === 'global') return getGlobalAgentDir();
+  if (layer === 'project') {
+    const project = detectProjectBrain();
+    if (!project) throw new Error('No project brain found. Run `npx total-recall init --project` to create one.');
+    return project.agentDir;
+  }
+  // Auto: project-local wins if it exists
+  const project = detectProjectBrain();
+  return project ? project.agentDir : getGlobalAgentDir();
+}
+
+/**
+ * Resolve the brain directory for a specific layer.
+ * @param {'global' | 'project' | 'auto'} [layer='auto']
+ */
+export function resolveBrainDir(layer = 'auto') {
+  return path.join(resolveAgentDir(layer), 'skills', 'total-recall');
+}
+
+/**
+ * Get both brain layers for the current context.
+ * @returns {{ global: { agentDir: string, brainDir: string }, project: { agentDir: string, brainDir: string } | null }}
+ */
+export function getBothBrains() {
+  const globalAgentDir = getGlobalAgentDir();
+  const globalBrainDir = getGlobalBrainDir();
+  const project = detectProjectBrain();
+  return {
+    global: { agentDir: globalAgentDir, brainDir: globalBrainDir },
+    project,
+  };
+}
+
+/**
+ * Determine the default layer for a memory category.
+ * Always defaults to project brain. Use --global to explicitly target global.
+ */
+export function defaultLayerForCategory(_category) {
+  return 'project';
+}