total-recall-brain 3.1.0

package/src/server/route-manifest.json

@@ -0,0 +1,77 @@
+[
+  { "method": "GET", "path": "/api/memory" },
+  { "method": "GET", "path": "/api/memory/stats" },
+  { "method": "GET", "path": "/api/memory/:slug" },
+  { "method": "POST", "path": "/api/memory" },
+  { "method": "PUT", "path": "/api/memory/:slug" },
+  { "method": "PATCH", "path": "/api/memory/:slug" },
+  { "method": "DELETE", "path": "/api/memory/:slug" },
+  { "method": "GET", "path": "/api/keys" },
+  { "method": "POST", "path": "/api/keys" },
+  { "method": "DELETE", "path": "/api/keys/:id" },
+  { "method": "GET", "path": "/api/sessions" },
+  { "method": "GET", "path": "/api/sessions/:id" },
+  { "method": "POST", "path": "/api/sessions/ingest" },
+  { "method": "DELETE", "path": "/api/sessions/:id" },
+  { "method": "POST", "path": "/api/memory/search/semantic" },
+  { "method": "POST", "path": "/api/vault/compile" },
+  { "method": "POST", "path": "/api/dream" },
+  { "method": "GET", "path": "/api/vault/status" },
+  { "method": "POST", "path": "/api/sandbox" },
+  { "method": "GET", "path": "/api/config" },
+  { "method": "GET", "path": "/v1/models" },
+  { "method": "GET", "path": "/.well-known/total-recall.json" },
+  { "method": "GET", "path": "/api" },
+  { "method": "GET", "path": "/api/research" },
+  { "method": "POST", "path": "/api/research" },
+  { "method": "PATCH", "path": "/api/research/:id" },
+  { "method": "DELETE", "path": "/api/research/:id" },
+  { "method": "GET", "path": "/api/integrations/active" },
+  { "method": "POST", "path": "/api/integrations/connect" },
+  { "method": "GET", "path": "/api/import/rules" },
+  { "method": "POST", "path": "/api/import/rules" },
+  { "method": "GET", "path": "/api/brain/export" },
+  { "method": "GET", "path": "/api/graph" },
+  { "method": "GET", "path": "/api/conflicts" },
+  { "method": "POST", "path": "/api/conflicts/resolve" },
+  { "method": "GET", "path": "/api/files" },
+  { "method": "GET", "path": "/api/skills" },
+  { "method": "GET", "path": "/api/skills/search" },
+  { "method": "POST", "path": "/api/skills/install" },
+  { "method": "GET", "path": "/api/skills/:name" },
+  { "method": "PUT", "path": "/api/skills/:name" },
+  { "method": "DELETE", "path": "/api/skills/:name" },
+  { "method": "GET", "path": "/api/logs/:type" },
+  { "method": "GET", "path": "/api/tasks" },
+  { "method": "POST", "path": "/api/tasks" },
+  { "method": "GET", "path": "/api/config-json" },
+  { "method": "POST", "path": "/api/config-json" },
+  { "method": "GET", "path": "/api/usage" },
+  { "method": "GET", "path": "/api/config/:name" },
+  { "method": "PUT", "path": "/api/config/:name" },
+  { "method": "POST", "path": "/api/capture/:source" },
+  { "method": "POST", "path": "/auth/login" },
+  { "method": "POST", "path": "/auth/logout" },
+  { "method": "POST", "path": "/auth/change-password" },
+  { "method": "GET", "path": "/auth/me" },
+  { "method": "GET", "path": "/auth/status" },
+  { "method": "POST", "path": "/auth/setup" },
+  { "method": "GET", "path": "/api/tts/status" },
+  { "method": "POST", "path": "/api/tts" },
+  { "method": "GET", "path": "/api/instructions" },
+  { "method": "PUT", "path": "/api/instructions" },
+  { "method": "GET", "path": "/api/ssss" },
+  { "method": "GET", "path": "/api/ssss/instructions" },
+  { "method": "GET", "path": "/api/ssss/skill/ssss" },
+  { "method": "GET", "path": "/api/ssss/spec" },
+  { "method": "GET", "path": "/api/ssss/references" },
+  { "method": "GET", "path": "/api/ssss/references/:name" },
+  { "method": "GET", "path": "/api/scripts" },
+  { "method": "GET", "path": "/api/scripts/:name" },
+  { "method": "PUT", "path": "/api/scripts/:name" },
+  { "method": "POST", "path": "/api/scripts/:name/run" },
+  { "method": "GET", "path": "/api/brains" },
+  { "method": "GET", "path": "/api/brains/:id/nodes" },
+  { "method": "GET", "path": "/api/gemini-models" },
+  { "method": "POST", "path": "/api/share" }
+]

package/src/server/routes/_shared.mjs

@@ -0,0 +1,93 @@
+/**
+ * Shared constants and response helpers used by every route module.
+ *
+ * Extracted from rest.mjs as part of the per-resource router refactor.
+ * Keep this file free of route definitions — it should be safe to import
+ * from any handler without circular concerns.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { agentDir, brainDir } from '../../core/config.mjs';
+import { logger } from '../../core/logger.mjs';
+
+export const AGENT_DIR    = process.env.AGENT_DIR || agentDir;
+export const BRAIN_DIR    = process.env.TR_BRAIN || path.join(AGENT_DIR, 'skills', 'total-recall');
+export const VAULT_DIR    = path.join(BRAIN_DIR, 'memory-vault');
+export const SKILLS_DIR   = path.join(AGENT_DIR, 'skills');
+export const DERIVED_DIR  = path.join(BRAIN_DIR, 'memory-derived');
+export const SESSIONS_DIR = path.join(BRAIN_DIR, 'sessions');
+export const INSTRUCTIONS = path.join(AGENT_DIR, 'INSTRUCTIONS.md');
+export const FILES_DIR    = path.join(BRAIN_DIR, 'files');
+export const TASKS_DIR    = path.join(BRAIN_DIR, 'scheduler', 'queue');
+export const CONFIG_DIR   = path.join(BRAIN_DIR, 'config');
+
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+export const MODEL_CATALOG_DIR = path.join(ROOT, 'models', 'catalog', 'total-recall');
+
+/**
+ * Resolve a brain-specific vault directory from the request.
+ *
+ * Reads `req.query.brain` (query param) or `req.body?.brainId` (body field).
+ * - If the value is `'global'` or missing, returns the default VAULT_DIR.
+ * - If it starts with `'project:'`, looks up the project brain in the
+ *   project-registry.json (same resolution logic as GET /api/brains/:id/nodes).
+ * - Falls back to VAULT_DIR if the resolved path doesn't exist.
+ *
+ * @param {import('express').Request} req
+ * @returns {string} Absolute path to the memory-vault directory
+ */
+export function resolveVaultFromQuery(req) {
+  const brainId = req.query?.brain || req.body?.brainId;
+
+  // No brain specified or explicitly global → default vault
+  if (!brainId || brainId === 'global') {
+    return VAULT_DIR;
+  }
+
+  if (brainId.startsWith('project:')) {
+    const projectName = brainId.slice('project:'.length);
+    const globalBrainDir = path.join(os.homedir(), '.agent', 'skills', 'total-recall');
+    const registryPath = path.join(globalBrainDir, 'config', 'project-registry.json');
+
+    if (!fs.existsSync(registryPath)) {
+      return VAULT_DIR;
+    }
+
+    try {
+      const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+      const project = registry.find(p => p.name === projectName);
+      if (project) {
+        const projectVaultDir = path.join(project.brainDir, 'memory-vault');
+        if (fs.existsSync(projectVaultDir)) {
+          return projectVaultDir;
+        }
+      }
+    } catch {
+      // Registry parse error — fall through to default
+    }
+  }
+
+  // Unknown brain ID format or resolution failed → default vault
+  return VAULT_DIR;
+}
+
+export function notFound(res, msg) {
+  return res.status(404).json({ error: msg || 'Not found' });
+}
+
+export function badRequest(res, msg) {
+  return res.status(400).json({ error: msg });
+}
+
+export function serverError(res, err) {
+  logger.error('rest', 'Internal server error', { error: err.message, stack: err.stack });
+  return res.status(500).json({ error: 'Internal server error' });
+}
+
+/** Strip the internal `body` field from a vault node into `content`. */
+export function sanitizeNode({ body, ...rest }) {
+  return { ...rest, content: body };
+}

package/src/server/routes/keys.mjs

@@ -0,0 +1,55 @@
+/**
+ * /api/keys/* routes — Personal Access Tokens
+ *
+ * - GET    /api/keys          list (no raw tokens)
+ * - POST   /api/keys          issue (returns raw token once)
+ * - DELETE /api/keys/:id      revoke
+ */
+
+import express from 'express';
+import { issueKey, revokeKey, loadKeys } from '../keys.mjs';
+import { requireAuth, requireScope } from '../auth.mjs';
+import { notFound, badRequest, serverError } from './_shared.mjs';
+
+const router = express.Router();
+
+router.get('/api/keys', requireAuth, requireScope('keys:read'), (req, res) => {
+  try {
+    const keys = loadKeys().map(({ token_hash, ...k }) => k);
+    res.json({ keys });
+  } catch (err) {
+    serverError(res, err);
+  }
+});
+
+router.post('/api/keys', requireAuth, requireScope('keys:write'), (req, res) => {
+  try {
+    const { name, scopes, expires_at } = req.body || {};
+    if (!name) return badRequest(res, 'name is required');
+    const key = issueKey(name, { scopes, expires_at });
+    res.status(201).json({
+      id:           key.id,
+      name:         key.name,
+      token:        key.token,           // only time it's returned in plaintext
+      token_prefix: key.token_prefix,
+      scopes:       key.scopes,
+      expires_at:   key.expires_at,
+      created_at:   key.created_at,
+      _warning:     'Save this token — it will not be shown again.',
+    });
+  } catch (err) {
+    serverError(res, err);
+  }
+});
+
+router.delete('/api/keys/:id', requireAuth, requireScope('keys:write'), (req, res) => {
+  try {
+    const key = revokeKey(req.params.id);
+    if (!key) return notFound(res, `Key not found: ${req.params.id}`);
+    res.json({ revoked: true, id: key.id, name: key.name });
+  } catch (err) {
+    serverError(res, err);
+  }
+});
+
+export { router as keysRouter };

package/src/server/routes/memory.mjs

@@ -0,0 +1,249 @@
+/**
+ * /api/memory/* routes
+ *
+ * - GET    /api/memory                list (q, category, tag, limit, offset)
+ * - GET    /api/memory/stats          counts by category
+ * - GET    /api/memory/:slug          read
+ * - POST   /api/memory                create
+ * - PUT    /api/memory/:slug          full replace
+ * - PATCH  /api/memory/:slug          partial update
+ * - DELETE /api/memory/:slug          delete
+ */
+
+import express from 'express';
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeNode, createMemoryNode, walkMd } from '../../core/vault.mjs';
+import { getNodes, invalidate } from '../../core/vault-cache.mjs';
+import { requireAuth, requireScope } from '../auth.mjs';
+import { compileSurface } from '../../core/surface.mjs';
+import { buildEmbeddingsIndex, buildSessionEmbeddingsIndex } from '../../core/embeddings.mjs';
+import { detectAndResolve } from '../../core/conflict-detector.mjs';
+import {
+  BRAIN_DIR,
+  VAULT_DIR,
+  SKILLS_DIR,
+  DERIVED_DIR,
+  SESSIONS_DIR,
+  INSTRUCTIONS,
+  notFound,
+  badRequest,
+  serverError,
+  sanitizeNode,
+  resolveVaultFromQuery,
+} from './_shared.mjs';
+
+const router = express.Router();
+
+function nodes(vaultDir = VAULT_DIR) {
+  return getNodes(vaultDir);
+}
+
+/**
+ * Trigger background SSSS semantic conflict resolution, surface compile, and embedding build.
+ * Auto-mutates the brain in real time when any fact is written, updated, or deleted!
+ */
+async function triggerMutation(node, vaultDir = VAULT_DIR) {
+  try {
+    // 1. Semantic conflict detection & auto-resolution (Sovereign OS Intelligence)
+    try {
+      const existing = nodes(vaultDir);
+      if (node && node.type === 'memory') {
+        detectAndResolve(node, existing, {
+          vaultDir,
+          inboxDir: path.join(BRAIN_DIR, 'memory-inbox'),
+        });
+      }
+    } catch (conflictErr) {
+      // Non-fatal fallback
+    }
+
+    // 2. Recompile instructions surface
+    await compileSurface({
+      vaultDir,
+      skillsDir:       SKILLS_DIR,
+      derivedDir:      DERIVED_DIR,
+      instructionsFile: INSTRUCTIONS,
+    });
+
+    // 3. Rebuild dense embeddings index incrementally in background
+    try {
+      const vaultNodes = nodes(vaultDir);
+      await buildEmbeddingsIndex(vaultNodes, DERIVED_DIR);
+      await buildSessionEmbeddingsIndex(SESSIONS_DIR, DERIVED_DIR);
+    } catch (embedErr) {
+      // Ollama/embeddings offline non-fatal
+    }
+  } catch (err) {
+    // Non-fatal background log
+  }
+}
+
+
+// SSSS v2 frontmatter fields we pass through verbatim from request bodies.
+const PASSTHROUGH_FIELDS = ['priority', 'modality', 'confidence', 'importance', 'status', 'related', 'sources'];
+
+router.get('/api/memory', requireAuth, requireScope('memory:read'), (req, res) => {
+  try {
+    const vaultDir = resolveVaultFromQuery(req);
+    let list = nodes(vaultDir);
+
+    const { q, category, tag, limit = '200', offset = '0' } = req.query;
+
+    if (q) {
+      const query = String(q).toLowerCase();
+      list = list.filter(n =>
+        [n.slug, n.title, n.category, (n.tags || []).join(' '), n.body]
+          .join(' ').toLowerCase().includes(query)
+      );
+    }
+    if (category) list = list.filter(n => n.category === category);
+    if (tag) list = list.filter(n => (n.tags || []).includes(tag));
+
+    const total = list.length;
+    const off   = Math.max(0, parseInt(offset, 10) || 0);
+    const lim   = Math.min(500, Math.max(1, parseInt(limit, 10) || 200));
+    const page  = list.slice(off, off + lim).map(sanitizeNode);
+
+    res.json({ total, offset: off, limit: lim, nodes: page });
+  } catch (err) {
+    serverError(res, err);
+  }
+});
+
+router.get('/api/memory/stats', requireAuth, requireScope('memory:read'), (req, res) => {
+  try {
+    const vaultDir = resolveVaultFromQuery(req);
+    const list = nodes(vaultDir);
+    const byCategory = {};
+    for (const n of list) {
+      byCategory[n.category] = (byCategory[n.category] || 0) + 1;
+    }
+    res.json({ total: list.length, by_category: byCategory });
+  } catch (err) {
+    serverError(res, err);
+  }
+});
+
+router.get('/api/memory/:slug', requireAuth, requireScope('memory:read'), (req, res) => {
+  try {
+    const vaultDir = resolveVaultFromQuery(req);
+    const node = nodes(vaultDir).find(n => n.slug === req.params.slug);
+    if (!node) return notFound(res, `Memory node not found: ${req.params.slug}`);
+    res.json(sanitizeNode(node));
+  } catch (err) {
+    serverError(res, err);
+  }
+});
+
+router.post('/api/memory', requireAuth, requireScope('memory:write'), (req, res) => {
+  try {
+    const vaultDir = resolveVaultFromQuery(req);
+    const { slug, title, category, content, body, tags } = req.body || {};
+    const actualContent = content || body;
+    if (!slug || !title || !category || !actualContent) {
+      return badRequest(res, 'Required fields: slug, title, category, content (or body)');
+    }
+    if (nodes(vaultDir).find(n => n.slug === slug)) {
+      return res.status(409).json({ error: `Node already exists: ${slug}. Use PUT to update.` });
+    }
+    const node = createMemoryNode({ slug, title, category, content: actualContent });
+    if (tags && Array.isArray(tags)) node.tags = tags;
+
+    for (const key of PASSTHROUGH_FIELDS) {
+      if (req.body[key] !== undefined) node[key] = req.body[key];
+    }
+
+    writeNode(node, vaultDir);
+    invalidate();
+    triggerMutation(node, vaultDir);
+    res.status(201).json(sanitizeNode(node));
+  } catch (err) {
+    serverError(res, err);
+  }
+});
+
+router.put('/api/memory/:slug', requireAuth, requireScope('memory:write'), (req, res) => {
+  try {
+    const vaultDir = resolveVaultFromQuery(req);
+    const { title, category, content, body, tags } = req.body || {};
+    const actualContent = content || body;
+    if (!title || !category || !actualContent) {
+      return badRequest(res, 'Required fields: title, category, content (or body)');
+    }
+    const node = createMemoryNode({ slug: req.params.slug, title, category, content: actualContent });
+    if (tags && Array.isArray(tags)) node.tags = tags;
+
+    for (const key of PASSTHROUGH_FIELDS) {
+      if (req.body[key] !== undefined) node[key] = req.body[key];
+    }
+
+    writeNode(node, vaultDir);
+    invalidate();
+    triggerMutation(node, vaultDir);
+    res.json(sanitizeNode(node));
+  } catch (err) {
+    serverError(res, err);
+  }
+});
+
+router.patch('/api/memory/:slug', requireAuth, requireScope('memory:write'), (req, res) => {
+  try {
+    const vaultDir = resolveVaultFromQuery(req);
+    const existing = nodes(vaultDir).find(n => n.slug === req.params.slug);
+    if (!existing) return notFound(res, `Memory node not found: ${req.params.slug}`);
+
+    const { title, category, content, body, tags } = req.body || {};
+    const actualContent = content || body || existing.body;
+    const updated = createMemoryNode({
+      slug:     existing.slug,
+      title:    title    ?? existing.title,
+      category: category ?? existing.category,
+      content:  actualContent,
+    });
+    updated.tags = tags ?? existing.tags ?? [];
+    updated.created_at = existing.created_at;
+
+    for (const key of PASSTHROUGH_FIELDS) {
+      if (existing[key] !== undefined) updated[key] = existing[key];
+    }
+    for (const key of PASSTHROUGH_FIELDS) {
+      if (req.body[key] !== undefined) updated[key] = req.body[key];
+    }
+
+    writeNode(updated, vaultDir);
+    invalidate();
+    triggerMutation(updated, vaultDir);
+    res.json(sanitizeNode(updated));
+  } catch (err) {
+    serverError(res, err);
+  }
+});
+
+router.delete('/api/memory/:slug', requireAuth, requireScope('memory:write'), (req, res) => {
+  try {
+    const vaultDir = resolveVaultFromQuery(req);
+    const list = nodes(vaultDir);
+    const node = list.find(n => n.slug === req.params.slug);
+    if (!node) return notFound(res, `Memory node not found: ${req.params.slug}`);
+
+    if (node._filePath && fs.existsSync(node._filePath)) {
+      fs.unlinkSync(node._filePath);
+    } else {
+      for (const file of walkMd(vaultDir)) {
+        const raw = fs.readFileSync(file, 'utf8');
+        if (raw.includes(`slug: ${req.params.slug}`)) {
+          fs.unlinkSync(file);
+          break;
+        }
+      }
+    }
+    invalidate();
+    triggerMutation(null, vaultDir);
+    res.json({ deleted: true, slug: req.params.slug });
+  } catch (err) {
+    serverError(res, err);
+  }
+});
+
+export { router as memoryRouter };