total-recall-brain 3.6.13 → 3.7.0

package/bin/total-recall.mjs

@@ -80,6 +80,7 @@ const COMMANDS = {
   help:     'help.mjs',
   collab:   'collab.mjs',
   command:  'command.mjs',
+  export:   'export.mjs',
 };
 function printHelp() {
   console.log(`
@@ -122,6 +123,7 @@ function printHelp() {
                                      into the vault (run before compile on first install)
     ingest [--watch]    Ingest IDE conversation logs (Claude Code, Codex, Gemini, etc.)
     ingest google-takeout <path>  Ingest Google Takeout export data
+    export <path> --okf Export memory vault as an OKF-compliant bundle
     connect <client>    Configure Cursor, Claude Code, Codex, UltraChat, Gemini, etc.
     sync [--watch]      Pull remote brain instructions into the current workspace
     relay <cmd>         Local background relay: ship IDE sessions to remote brain

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.6.13",
+  "version": "3.7.0",
   "description": "Sovereign AI system — database-free, SSSS-powered personal intelligence engine deployable to any POSIX host.",
   "type": "module",
   "bin": {

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

@@ -145,6 +145,38 @@ npx total-recall compile
 ```
 Synchronously rebuild the entire memory index (derived embeddings) and regenerate prompt instruction shims (such as `INSTRUCTIONS.md`, `GEMINI.md`, `AGENTS.md`, etc.).
 
+### 5. Ingest OKF Bundle
+```bash
+npx total-recall ingest okf <path> [options]
+```
+Recursively parse and ingest an Open Knowledge Format (OKF v0.1 Draft) bundle directory.
+*   **Options**:
+    *   `--dry-run`: Parse and validate nodes without writing files.
+    *   `--category <name>`: Override and force all imported nodes to a specific category.
+    *   `--importance <1-5>`: Override importance for imported nodes.
+    *   `--on-conflict <strategy>`: Slug conflict behavior (`overwrite`, `skip`, `warn` - default is `warn`).
+    *   `--type-map <json>`: Custom type-to-category mapping JSON.
+*   *Note*: Spawns an asynchronous background surface compile process immediately on successful ingest.
+
+### 6. Export OKF Bundle
+```bash
+npx total-recall export <path> [options]
+```
+Export the memory vault into an OKF-compliant directory structure.
+*   **Options**:
+    *   `--okf`: Run in OKF export mode.
+    *   `--strip-ssss`: Strip all SSSS-specific metadata parameters from output frontmatter.
+    *   `--format <type>`: Package output as archive (`tar.gz`).
+    *   `--global` / `--project`: Target scope layer.
+
+### 7. Lint OKF Compliance
+```bash
+npx total-recall lint --okf [options]
+```
+Scan vault memory nodes and check for OKF metadata compliance (presence of title, description, tags, and updated timestamp).
+*   **Options**:
+    *   `--strict`: Promote compliance warnings to errors and exit with code 1.
+
 ---
 
 ## 🌐 DIRECT REST API REFERENCE

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

@@ -127,6 +127,9 @@ SSSS schema v2. Required schema v2 knowledge-graph fields are:
 
 Invariants additionally use `priority: absolute` and `immutable: true`.
 
+### OKF Compatibility Note
+SSSS v0.2 is a strict superset of the Open Knowledge Format (OKF v0.1 Draft). SSSS memory nodes are fully OKF-compatible, as they are Markdown files containing a YAML frontmatter block with a `type` field (which maps to SSSS `category` via the OKF adapter). To bridge the format seamlessly, SSSS v0.2 extends `MemoryNodeSchema` with two optional OKF-standard fields: `description` and `resource` (supporting non-HTTP URIs such as `gs://` or `s3://`).
+
 Memory validation is owned by `TotalRecallMemoryValidator`, not by generic loose
 frontmatter checks. No memory path may be committed with zero validation.
 

package/src/cli/export.mjs

@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseLayerFlag, resolveBrainDir } from './agent-dir.mjs';
+import { exportBundle } from '../core/okf-adapter.mjs';
+
+export default async function exportCommand(args) {
+  const { layer, remainingArgs } = parseLayerFlag(args);
+
+  const opts = {
+    outputPath: null,
+    okf: false,
+    format: 'dir',
+    stripSsss: false,
+    help: false
+  };
+
+  for (let i = 0; i < remainingArgs.length; i++) {
+    const arg = remainingArgs[i];
+    const val = remainingArgs[i + 1];
+
+    switch (arg) {
+      case '--okf':
+        opts.okf = true;
+        break;
+      case '--format':
+        if (val) { opts.format = val; i++; }
+        break;
+      case '--strip-ssss':
+        opts.stripSsss = true;
+        break;
+      case '--help': case '-h':
+        opts.help = true;
+        break;
+      default:
+        if (!arg.startsWith('-') && !opts.outputPath) {
+          opts.outputPath = arg;
+        }
+    }
+  }
+
+  if (opts.help || !opts.outputPath || !opts.okf) {
+    printExportHelp();
+    return;
+  }
+
+  const brainDir = resolveBrainDir(layer);
+  const vaultDir = path.join(brainDir, 'memory-vault');
+
+  console.log(`\n  📤 Exporting Memory Vault to OKF Bundle...`);
+  console.log(`  🧠 Source Brain: ${layer} (${vaultDir})`);
+  console.log(`  📂 Destination:  ${opts.outputPath} (Format: ${opts.format})`);
+
+  try {
+    const report = await exportBundle(vaultDir, opts.outputPath, {
+      format: opts.format,
+      stripSsss: opts.stripSsss
+    });
+
+    console.log(`\n  Export Summary:`);
+    console.log(`  🟢 Exported: ${report.exported.length} concepts`);
+    console.log(`  📄 generated index.md`);
+    console.log(`  📄 generated log.md`);
+    console.log(`  ✅ Export completed successfully.\n`);
+  } catch (err) {
+    console.error(`\n  ❌ Export failed: ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+function printExportHelp() {
+  console.log(`
+  total-recall export — Export Total Recall knowledge bases
+
+  Usage:
+    total-recall export <output-path> --okf [options]
+
+  Options:
+    --okf                     Export as an Open Knowledge Format (OKF) bundle (required)
+    --format <dir|tar.gz>     Output format: directory or compressed tarball (default: dir)
+    --strip-ssss              Remove all SSSS-specific metadata fields, leaving only pure OKF
+    --global                  Source from the global brain
+    --project                 Source from the project brain (default)
+    --help, -h                Show this help
+  `);
+}

package/src/cli/ingest-okf.mjs

@@ -0,0 +1,132 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseLayerFlag, resolveBrainDir } from './agent-dir.mjs';
+import { importBundle } from '../core/okf-adapter.mjs';
+
+export async function runOkfIngest(args) {
+  const { layer, remainingArgs } = parseLayerFlag(args);
+  
+  const opts = {
+    bundlePath: null,
+    dryRun: false,
+    category: null,
+    importance: null,
+    onConflict: 'warn',
+    typeMap: null,
+    help: false
+  };
+
+  for (let i = 0; i < remainingArgs.length; i++) {
+    const arg = remainingArgs[i];
+    const val = remainingArgs[i + 1];
+
+    switch (arg) {
+      case '--dry-run':
+        opts.dryRun = true;
+        break;
+      case '--category':
+        if (val) { opts.category = val; i++; }
+        break;
+      case '--importance':
+        if (val) { opts.importance = parseInt(val, 10); i++; }
+        break;
+      case '--on-conflict':
+        if (val) { opts.onConflict = val; i++; }
+        break;
+      case '--type-map':
+        if (val) {
+          const map = {};
+          const pairs = val.split(',');
+          for (const pair of pairs) {
+            const parts = pair.split('=');
+            if (parts.length === 2) {
+              map[parts[0].trim()] = parts[1].trim();
+            }
+          }
+          opts.typeMap = map;
+          i++;
+        }
+        break;
+      case '--help': case '-h':
+        opts.help = true;
+        break;
+      default:
+        if (!arg.startsWith('-') && !opts.bundlePath) {
+          opts.bundlePath = arg;
+        }
+    }
+  }
+
+  if (opts.help || !opts.bundlePath) {
+    printIngestOkfHelp();
+    return;
+  }
+
+  const brainDir = resolveBrainDir(layer);
+  const vaultDir = path.join(brainDir, 'memory-vault');
+
+  console.log(`\n  📥 Importing OKF Bundle from: ${opts.bundlePath}`);
+  console.log(`  🧠 Target Brain: ${layer} (${vaultDir})`);
+  if (opts.dryRun) console.log('  ⚠️  DRY RUN: No actual writes will be committed.');
+
+  const report = await importBundle(opts.bundlePath, vaultDir, {
+    dryRun: opts.dryRun,
+    category: opts.category,
+    importance: opts.importance,
+    onConflict: opts.onConflict,
+    typeMap: opts.typeMap
+  });
+
+  console.log(`\n  Import Summary:`);
+  console.log(`  🟢 Imported: ${report.imported.length} concepts`);
+  console.log(`  🟡 Skipped:  ${report.skipped.length} concepts`);
+  console.log(`  🔴 Errors:   ${report.errors.length} concepts`);
+
+  if (report.skipped.length > 0) {
+    console.log(`\n  Skipped detail:`);
+    for (const item of report.skipped) {
+      console.log(`    • ${item.file}: ${item.reason}`);
+    }
+  }
+
+  if (report.errors.length > 0) {
+    console.log(`\n  Errors detail:`);
+    for (const item of report.errors) {
+      console.log(`    • ${item.file}: ${item.error}`);
+    }
+    process.exit(1);
+  }
+
+  if (report.imported.length > 0 && !opts.dryRun) {
+    // Recompile active memory surfaces and indexes in the background to avoid blocking the CLI call.
+    console.log('\n  ⏳ Recompiling active memory surfaces and indexes in the background...');
+    try {
+      const { spawn } = await import('node:child_process');
+      const child = spawn(process.argv[0], [process.argv[1], 'compile'], {
+        detached: true,
+        stdio: 'ignore'
+      });
+      child.unref();
+      console.log('  ✅ Background compilation started.');
+    } catch (err) {
+      console.warn(`  ⚠️  Background recompilation spawn failed: ${err.message}`);
+    }
+  }
+}
+
+function printIngestOkfHelp() {
+  console.log(`
+  Usage:
+    total-recall ingest okf <bundle-path> [options]
+
+  Options:
+    --dry-run                 Validate concepts and preview import without writing
+    --category <name>         Override and force category for all imported concepts
+    --importance <1-5>        Override default importance (default: 3)
+    --on-conflict <strategy>  Strategy for duplicate slugs: 'skip' | 'warn' | 'overwrite' (default: warn)
+    --type-map <mapping>      Custom type mappings. Format: "Type A=facts,Type B=concepts"
+    --global                  Target the global brain
+    --project                 Target the project brain (default)
+    --help, -h                Show this help
+  `);
+}

package/src/cli/ingest.mjs

@@ -38,6 +38,8 @@ function printHelp() {
   Subcommands:
     google-takeout <path>  Ingest Google Takeout export data
                            Use 'total-recall ingest google-takeout --help' for details
+    okf <path>             Ingest an Open Knowledge Format (OKF) bundle directory
+                           Use 'total-recall ingest okf --help' for details
 
   IDE Session Ingest:
     Scans known local directories for conversation history from:
@@ -52,6 +54,7 @@ function printHelp() {
   Usage:
     total-recall ingest [options]
     total-recall ingest google-takeout <path> [options]
+    total-recall ingest okf <path> [options]
 
   Options:
     --sources <list>   Comma-separated source filter (e.g. claude-code,codex)
@@ -68,6 +71,12 @@ export default async function ingest(args) {
     return;
   }
 
+  if (args[0] === 'okf') {
+    const { runOkfIngest } = await import('./ingest-okf.mjs');
+    await runOkfIngest(args.slice(1));
+    return;
+  }
+
   const opts = parseArgs(args);
   if (opts.help) { printHelp(); return; }
 

package/src/cli/lint.mjs

@@ -24,12 +24,13 @@ const AGENT_DIR = resolveAgentDir();
 const BRAIN_DIR = resolveBrainDir();
 
 function parseArgs(args) {
-  const opts = { vault: null, strict: false, json: false, help: false };
+  const opts = { vault: null, strict: false, json: false, help: false, okf: false };
   for (let i = 0; i < args.length; i++) {
     switch (args[i]) {
       case '--vault': opts.vault = args[++i]; break;
       case '--strict': opts.strict = true; break;
       case '--json': opts.json = true; break;
+      case '--okf': opts.okf = true; break;
       case '--help': case '-h': opts.help = true; break;
     }
   }
@@ -38,16 +39,17 @@ function parseArgs(args) {
 
 function printHelp() {
   console.log(`
-  total-recall lint — Validate vault nodes against SSSS schema v2
+  total-recall lint — Validate vault nodes against SSSS schema v2 or OKF spec
 
   Scans all .md files in the memory vault and validates their YAML
-  frontmatter against the Zod schemas defined in src/core/schema.mjs.
+  frontmatter against the Zod schemas or checks for OKF compliance.
 
   Usage: total-recall lint [options]
 
   Options:
     --vault <path>     Override vault directory (default: ~/.agent/memory-vault)
     --strict           Treat warnings as errors (exit 1 on any issue)
+    --okf              Verify OKF v0.1 draft metadata compliance
     --json             Output results as JSONL
     --help, -h         Show this help
 
@@ -63,6 +65,40 @@ export default async function lint(args) {
 
   const vaultDir = opts.vault || path.join(BRAIN_DIR, 'memory-vault');
 
+  if (opts.okf) {
+    const { lintOkfCompliance } = await import('../core/okf-adapter.mjs');
+    const report = lintOkfCompliance(vaultDir, { strict: opts.strict });
+
+    if (opts.json) {
+      console.log(JSON.stringify(report));
+    } else {
+      console.error(`\n  🔍 OKF Compliance Report for: ${vaultDir}\n`);
+      for (const warn of report.warnings) {
+        console.error(`  ⚠️  ${warn.file}: ${warn.message}`);
+      }
+      for (const err of report.errors) {
+        console.error(`  ❌ ${err.file}: ${err.message}`);
+      }
+
+      console.error(`\n  ── Results ──`);
+      console.error(`     Total scanned:  ${report.total}`);
+      console.error(`     Pass:           ${report.pass ? 'Yes' : 'No'}`);
+      console.error(`     Warnings:       ${report.warnings.length}`);
+      console.error(`     Errors:         ${report.errors.length}`);
+
+      if (report.pass) {
+        console.error(`\n  ✅ OKF Compliance passed\n`);
+      } else {
+        console.error(`\n  ❌ OKF Compliance failed\n`);
+      }
+    }
+
+    if (!report.pass) {
+      process.exit(1);
+    }
+    return;
+  }
+
   if (!opts.json) {
     console.error(`\n  🔍 Linting vault: ${vaultDir}\n`);
   }

package/src/core/okf-adapter.mjs

@@ -0,0 +1,464 @@
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import matter from 'gray-matter';
+import { safeStringify } from './vault.mjs';
+import { writeNodeValidated } from './validated-write.mjs';
+import { getNodes } from './vault-cache.mjs';
+import { validateMemoryNode } from './total-recall-memory-validator.mjs';
+
+// ─── DEFAULT OKF TYPE MAP ──────────────────────────────────────────────────
+export const DEFAULT_OKF_TYPE_MAP = {
+  'BigQuery Table':    'facts',
+  'BigQuery Dataset':  'facts',
+  'API Endpoint':      'facts',
+  'Metric':            'concepts',
+  'Playbook':          'patterns',
+  'Runbook':           'patterns',
+  'Reference':         'facts',
+  'Architecture':      'concepts',
+  'Decision':          'decisions',
+  'Policy':            'invariants',
+  'Best Practice':     'patterns',
+  'Anti-Pattern':      'anti-patterns',
+  '*':                 'facts',
+};
+
+// ─── Pure Mapping Functions ────────────────────────────────────────────────
+
+/**
+ * Derives a valid SSSS subject from a title.
+ */
+function deriveSubject(title) {
+  let subject = 'okf.concept';
+  if (title) {
+    const cleaned = title.replace(/[^a-zA-Z0-9_\s.-]/g, '').trim();
+    if (cleaned) {
+      const words = cleaned.split(/\s+/);
+      if (words.length > 0 && words[0]) {
+        subject = words[0].toLowerCase();
+      }
+    }
+  }
+  return /^[a-zA-Z0-9_\s.-]+$/.test(subject) ? subject : 'okf.concept';
+}
+
+/**
+ * Derives a description from a Markdown body if absent.
+ */
+function deriveDescription(body) {
+  if (!body) return undefined;
+  const match = body.trim().match(/^[^.!?\n]+[.!?]/);
+  return match ? match[0].trim() : body.trim().split('\n')[0].trim();
+}
+
+/**
+ * Capitalizes SSSS category to OKF type.
+ */
+function categoryToOkfType(category) {
+  const reverseMap = {
+    'facts': 'Fact',
+    'concepts': 'Concept',
+    'patterns': 'Pattern',
+    'invariants': 'Invariant',
+    'decisions': 'Decision',
+    'anti-patterns': 'Anti-Pattern',
+    'preferences': 'Preference',
+    'corrections': 'Correction',
+    'lore': 'Lore'
+  };
+  return reverseMap[category] || (category.charAt(0).toUpperCase() + category.slice(1));
+}
+
+/**
+ * Convert an OKF concept (frontmatter + body) into an SSSS memory node.
+ */
+export function okfConceptToSsssNode(okfFrontmatter, okfBody, conceptId, options = {}) {
+  if (!okfFrontmatter || typeof okfFrontmatter !== 'object') {
+    return null;
+  }
+
+  const actualTypeMap = { ...DEFAULT_OKF_TYPE_MAP, ...options.typeMap };
+  const okfType = okfFrontmatter.type;
+
+  let category = options.category;
+  if (!category) {
+    category = actualTypeMap[okfType] || actualTypeMap['*'] || 'facts';
+  }
+
+  // Derive slug
+  let slug = conceptId || 'unnamed-concept';
+  if (slug.endsWith('.md')) {
+    slug = slug.slice(0, -3);
+  }
+  slug = slug.replace(/^(\.\.?[\/\\])+/, '').replace(/^[\/\\]+/, '');
+  slug = slug.replace(/[\/\\]/g, '-').toLowerCase();
+
+  const title = okfFrontmatter.title || conceptId || 'Untitled Concept';
+  const subject = okfFrontmatter.title ? deriveSubject(okfFrontmatter.title) : 'okf.concept';
+  const object = okfFrontmatter.type || 'concept';
+
+  // Parse ISO 8601 timestamp
+  let timestamp = new Date().toISOString();
+  if (okfFrontmatter.timestamp) {
+    if (okfFrontmatter.timestamp instanceof Date) {
+      timestamp = okfFrontmatter.timestamp.toISOString();
+    } else if (typeof okfFrontmatter.timestamp === 'string') {
+      timestamp = okfFrontmatter.timestamp;
+    }
+  }
+
+  const importance = (options.importance !== undefined && options.importance !== null)
+    ? options.importance
+    : ((options.defaultImportance !== undefined && options.defaultImportance !== null)
+        ? options.defaultImportance
+        : 3);
+
+  const node = {
+    type: 'memory',
+    slug,
+    category,
+    title,
+    description: okfFrontmatter.description || undefined,
+    resource: okfFrontmatter.resource || undefined,
+    status: 'active',
+    confidence: 0.8,
+    importance,
+    created: timestamp,
+    updated: timestamp,
+    last_accessed: new Date().toISOString(),
+    source: {
+      type: 'okf-import',
+      session_id: crypto.randomUUID(),
+      agent: 'total-recall-cli',
+      evidence_count: 1,
+    },
+    supersedes: [],
+    superseded_by: null,
+    contradicts: [],
+    tags: Array.isArray(okfFrontmatter.tags) ? okfFrontmatter.tags : (okfFrontmatter.tags ? [okfFrontmatter.tags] : []),
+    related: [],
+    routes_to_skills: [],
+    sentiment_polarity: 'descriptive',
+    sentiment_target: subject,
+    modality: 'descriptive',
+    subject,
+    predicate: 'describes',
+    object,
+    decay: {
+      half_life_days: 30,
+      access_count: 0,
+    },
+    schema_version: 2,
+    body: okfBody || '',
+  };
+
+  return node;
+}
+
+/**
+ * Convert an SSSS memory node into an OKF-compliant concept.
+ */
+export function ssssNodeToOkfConcept(ssssNode) {
+  if (!ssssNode || typeof ssssNode !== 'object') {
+    return null;
+  }
+
+  const desc = ssssNode.description || deriveDescription(ssssNode.body);
+
+  const frontmatter = {
+    ...ssssNode,
+    type: categoryToOkfType(ssssNode.category),
+    title: ssssNode.title,
+    description: desc || undefined,
+    resource: ssssNode.resource || undefined,
+    tags: ssssNode.tags || [],
+    timestamp: ssssNode.updated || ssssNode.created || new Date().toISOString(),
+  };
+
+  // Clean up SSSS node-specific keys we don't want as top-level frontmatter if they match the body/filepath fields
+  delete frontmatter.body;
+  delete frontmatter._filePath;
+  delete frontmatter._filepath;
+  delete frontmatter._file_path;
+
+  return {
+    frontmatter,
+    body: ssssNode.body || '',
+  };
+}
+
+// ─── Bundle Operations (Placeholders to be fully implemented) ────────────────
+
+export async function importBundle(bundlePath, vaultDir, options = {}) {
+  const imported = [];
+  const skipped = [];
+  const errors = [];
+
+  if (!fs.existsSync(bundlePath)) {
+    errors.push({ file: bundlePath, error: 'Bundle directory does not exist' });
+    return { imported, skipped, errors };
+  }
+
+  // Helper to walk directory recursively, skipping index.md and log.md
+  function walk(dir) {
+    let files = [];
+    const list = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of list) {
+      const name = entry.name;
+      // Skip reserved filenames at any directory level
+      if (name === 'index.md' || name === 'log.md') {
+        continue;
+      }
+      const fullPath = path.join(dir, name);
+      if (entry.isDirectory()) {
+        files = files.concat(walk(fullPath));
+      } else if (name.endsWith('.md')) {
+        files.push(fullPath);
+      }
+    }
+    return files;
+  }
+
+  let mdFiles = [];
+  try {
+    mdFiles = walk(bundlePath);
+  } catch (err) {
+    errors.push({ file: bundlePath, error: err.message });
+    return { imported, skipped, errors };
+  }
+
+  // Get existing slugs to handle conflicts
+  let existingSlugs = new Set();
+  try {
+    const existing = getNodes(vaultDir);
+    existingSlugs = new Set(existing.map(n => n.slug));
+  } catch (err) {
+    // If vault dir doesn't exist yet, it's fine, we'll create it during writes
+  }
+
+  const onConflict = options.onConflict || 'warn';
+
+  for (const filePath of mdFiles) {
+    const relPath = path.relative(bundlePath, filePath);
+    let raw;
+    try {
+      raw = fs.readFileSync(filePath, 'utf8');
+    } catch (err) {
+      errors.push({ file: relPath, error: `Failed to read file: ${err.message}` });
+      continue;
+    }
+
+    let parsed;
+    try {
+      parsed = matter(raw);
+    } catch (err) {
+      errors.push({ file: relPath, error: `Failed to parse YAML frontmatter: ${err.message}` });
+      continue;
+    }
+
+    // Skip if there's no frontmatter data or if the required OKF 'type' field is missing
+    if (!parsed || !parsed.data || Object.keys(parsed.data).length === 0 || !parsed.data.type) {
+      skipped.push({ file: relPath, reason: 'missing frontmatter or type field' });
+      continue;
+    }
+
+    const node = okfConceptToSsssNode(parsed.data, parsed.content, relPath, options);
+    if (!node) {
+      skipped.push({ file: relPath, reason: 'failed to map to SSSS node' });
+      continue;
+    }
+
+    // Handle slug conflict
+    if (existingSlugs.has(node.slug)) {
+      if (onConflict === 'skip') {
+        skipped.push({ file: relPath, reason: `conflict (slug ${node.slug} exists)` });
+        continue;
+      } else if (onConflict === 'warn') {
+        console.warn(`[OKF Import Warning] Slug collision: '${node.slug}' already exists. Overwriting.`);
+      }
+    }
+
+    try {
+      const writeResult = writeNodeValidated(node, vaultDir, {
+        dryRun: options.dryRun || false,
+        agentRole: options.agentRole || 'admin'
+      });
+
+      if (!writeResult.success) {
+        let errMsg = writeResult.error || 'Validation failed';
+        if (writeResult.repair?.field_errors) {
+          const details = writeResult.repair.field_errors.map(fe => `${fe.field}: ${fe.issue}`).join(', ');
+          errMsg += ` (${details})`;
+        }
+        errors.push({ file: relPath, error: errMsg });
+      } else {
+        imported.push({ slug: node.slug, file: relPath });
+        if (!options.dryRun) {
+          existingSlugs.add(node.slug);
+        }
+      }
+    } catch (err) {
+      errors.push({ file: relPath, error: `Write error: ${err.message}` });
+    }
+  }
+
+  return { imported, skipped, errors };
+}
+
+export async function exportBundle(vaultDir, outputDir, options = {}) {
+  const { execSync } = await import('node:child_process');
+  const os = await import('node:os');
+
+  const format = options.format || 'dir';
+  const stripSsss = options.stripSsss || false;
+
+  let targetDir = outputDir;
+  let isTar = format === 'tar.gz';
+  let tempDir = null;
+
+  if (isTar) {
+    tempDir = path.join(os.tmpdir(), `okf-export-${crypto.randomUUID()}`);
+    targetDir = tempDir;
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  const nodes = getNodes(vaultDir);
+  const exported = [];
+
+  const conceptsByCategory = {};
+
+  for (const node of nodes) {
+    const concept = ssssNodeToOkfConcept(node);
+    if (!concept) continue;
+
+    if (stripSsss) {
+      const allowed = ['type', 'title', 'description', 'resource', 'tags', 'timestamp'];
+      const stripped = {};
+      for (const key of allowed) {
+        if (concept.frontmatter[key] !== undefined) {
+          stripped[key] = concept.frontmatter[key];
+        }
+      }
+      concept.frontmatter = stripped;
+    }
+
+    const category = node.category || 'facts';
+    const catDir = path.join(targetDir, category);
+    fs.mkdirSync(catDir, { recursive: true });
+
+    const filename = `${node.slug}.md`;
+    const destPath = path.join(catDir, filename);
+
+    const fileContent = safeStringify(concept.body, concept.frontmatter);
+    fs.writeFileSync(destPath, fileContent, 'utf8');
+
+    exported.push({ slug: node.slug, file: path.join(category, filename) });
+
+    if (!conceptsByCategory[category]) {
+      conceptsByCategory[category] = [];
+    }
+    conceptsByCategory[category].push({
+      title: node.title,
+      relPath: `./${category}/${filename}`,
+      description: concept.frontmatter.description || ''
+    });
+  }
+
+  // Generate index.md
+  let indexContent = '# Knowledge Bundle Index\n\n';
+  for (const [category, list] of Object.entries(conceptsByCategory)) {
+    const catHeader = category.charAt(0).toUpperCase() + category.slice(1);
+    indexContent += `## ${catHeader}\n`;
+    for (const item of list) {
+      const descSuffix = item.description ? ` - ${item.description}` : '';
+      indexContent += `- [${item.title}](${item.relPath})${descSuffix}\n`;
+    }
+    indexContent += '\n';
+  }
+  fs.writeFileSync(path.join(targetDir, 'index.md'), indexContent, 'utf8');
+
+  // Generate log.md
+  let logContent = '# Bundle Update History\n\n';
+  const auditPath = path.join(vaultDir, '.events', 'audit.jsonl');
+  if (fs.existsSync(auditPath)) {
+    try {
+      const lines = fs.readFileSync(auditPath, 'utf8').trim().split('\n');
+      for (const line of lines) {
+        if (!line) continue;
+        const event = JSON.parse(line);
+        const date = event.ts ? new Date(event.ts).toISOString().replace(/\.\d+Z$/, 'Z') : 'Unknown Date';
+        const operation = event.payload?.resolved_type || 'mutation';
+        logContent += `- **${date}**: Operation '${operation}' committed at \`${event.subject || event.path || ''}\`\n`;
+      }
+    } catch (err) {
+      logContent += `Failed to parse audit history: ${err.message}\n`;
+    }
+  } else {
+    logContent += 'No update history available.\n';
+  }
+  fs.writeFileSync(path.join(targetDir, 'log.md'), logContent, 'utf8');
+
+  if (isTar) {
+    const tarFile = outputDir.endsWith('.tar.gz') ? outputDir : `${outputDir}.tar.gz`;
+    fs.mkdirSync(path.dirname(tarFile), { recursive: true });
+    execSync(`tar -czf "${tarFile}" -C "${targetDir}" .`);
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+
+  return {
+    exported,
+    indexGenerated: true,
+    logGenerated: true
+  };
+}
+
+export function lintOkfCompliance(vaultDir, options = {}) {
+  const strict = options.strict || false;
+  const nodes = getNodes(vaultDir);
+
+  const warnings = [];
+  const errors = [];
+
+  for (const node of nodes) {
+    const relPath = `${node.category}/${node.slug}.md`;
+    
+    // Check title
+    if (!node.title) {
+      const msg = `Missing title in ${relPath}`;
+      if (strict) errors.push({ file: relPath, message: msg });
+      else warnings.push({ file: relPath, message: msg });
+    }
+
+    // Check description
+    if (!node.description) {
+      const msg = `Missing description in ${relPath}`;
+      if (strict) errors.push({ file: relPath, message: msg });
+      else warnings.push({ file: relPath, message: msg });
+    }
+
+    // Check tags
+    if (!node.tags || !Array.isArray(node.tags) || node.tags.length === 0) {
+      const msg = `Missing or empty tags in ${relPath}`;
+      if (strict) errors.push({ file: relPath, message: msg });
+      else warnings.push({ file: relPath, message: msg });
+    }
+
+    // Check updated/created timestamp
+    if (!node.updated && !node.created) {
+      const msg = `Missing updated/created timestamp in ${relPath}`;
+      if (strict) errors.push({ file: relPath, message: msg });
+      else warnings.push({ file: relPath, message: msg });
+    }
+  }
+
+  const pass = errors.length === 0;
+
+  return {
+    total: nodes.length,
+    pass,
+    warnings,
+    errors
+  };
+}

package/src/core/schema.mjs

@@ -23,6 +23,8 @@ export const MemoryNodeSchema = z.object({
   slug: z.string(),
   category: z.string(),
   title: z.string(),
+  description: z.string().optional(),
+  resource: z.string().optional(),
   status: z.enum(['active', 'superseded', 'deprecated', 'draft']),
   confidence: z.number().min(0).max(1).optional(),
   importance: z.number().int().min(1).max(5).optional(),

package/src/core/surface.mjs

@@ -10,13 +10,29 @@ import {
 } from './memory-layers.mjs';
 
 /**
- * Extract [[slug]] wikilink references from body text.
+ * Extract [[slug]] wikilink references and relative Markdown link targets from body text.
  * Native TR link resolution; Obsidian renders them as graph edges.
  */
 export function extractWikilinks(body) {
   if (!body) return [];
   const matches = body.match(/\[\[([^\]]+)\]\]/g) || [];
-  return [...new Set(matches.map(m => m.slice(2, -2).split('|')[0].trim()))];
+  const wikilinks = matches.map(m => m.slice(2, -2).split('|')[0].trim());
+
+  const mdLinkMatches = body.matchAll(/\[([^\]]*)\]\(([^)]+)\)/g);
+  const mdLinks = [];
+  for (const match of mdLinkMatches) {
+    const url = match[2].trim();
+    if (/^https?:\/\//i.test(url)) {
+      continue;
+    }
+    const base = path.basename(url);
+    const targetSlug = base.endsWith('.md') ? base.slice(0, -3) : base;
+    if (targetSlug) {
+      mdLinks.push(targetSlug);
+    }
+  }
+
+  return [...new Set([...wikilinks, ...mdLinks])];
 }
 
 /**
@@ -564,7 +580,8 @@ export async function compileSurface({ vaultDir, skillsDir, derivedDir, instruct
     category: n.category,
     status: n.status,
     confidence: n.confidence,
-    memory_layer: inferMemoryLayer(n)
+    memory_layer: inferMemoryLayer(n),
+    links: extractWikilinks(n.body || '')
   }));
   atomicWrite(path.join(derivedDir, 'graph-index.jsonl'), graphIndex.map(n => JSON.stringify(n)).join('\n'));
   atomicWrite(