trucontext 0.7.0 → 0.8.0

package/README.md

@@ -17,17 +17,20 @@ That's it. No API keys to copy, no config files to edit. Browser-based OAuth, th
 ## The 30-Second Version
 
 ```bash
-# Create an entity for the person your agent works with
-npx trucontext entities create --id dustin --type Person \
-  --properties '{"name": "Dustin", "role": "founder"}' \
-  --recipe recipe:personal-assistant-memory
+# Create a root node — the intelligence boundary for your agent's memory
+npx trucontext roots create --id dustin --type Person \
+  --recipe recipe:personal-assistant-memory \
+  --properties '{"name": "Dustin", "role": "founder"}'
+
+# Set it as the active root for queries
+npx trucontext roots use dustin
 
 # Ingest what your agent learned
 npx trucontext ingest "Dustin prefers async communication and dark mode. \
   He values clean code over backwards compatibility." \
   --context dustin:ABOUT --confidence 0.85 --temporal
 
-# Ask an intelligent question
+# Ask an intelligent question (scoped to the root's ego network)
 npx trucontext query "What does Dustin prefer?"
 ```
 
@@ -135,28 +138,35 @@ Observe → Capture → Sleep → Wake → Query → Observe → ...
 ### Apps
 | Command | Description |
 |---------|-------------|
-| `init [name]` | Create a new app with AI-generated schema |
+| `init [name]` | Create a new app with schema + root node |
 | `apps` | List your apps |
 | `use <app>` | Set the active app |
 
+### Root Nodes
+| Command | Description |
+|---------|-------------|
+| `roots create` | Create a root node with recipe and dreamers |
+| `roots list` | List all root nodes |
+| `roots show <id>` | Show root node details and linked roots |
+| `roots update <id>` | Update recipe, dreamers, or properties |
+| `roots delete <id>` | Demote to regular entity |
+| `roots use <id>` | Set active root for queries |
+
 ### Data
 | Command | Description |
 |---------|-------------|
-| `ingest <source>` | Ingest text or file with confidence, temporal, and context linking |
-| `query <question>` | Query the intelligent knowledge graph |
-| `recall <query>` | Semantic memory recall with graph expansion |
+| `ingest <source>` | Ingest text or file (requires `--context`) |
+| `query <question>` | Query the graph (requires active root or `--root`) |
+| `recall <query>` | Semantic recall (requires active root or `--root`) |
 
-### Structure
+### Entities
 | Command | Description |
 |---------|-------------|
 | `entities list` | List entities |
-| `entities create` | Create entity with recipe, confidence, temporal, contexts |
+| `entities create` | Create entity (requires `--context`) |
 | `entities get <id>` | Get entity details |
-| `entities update <id>` | Update entity properties, recipe, heartbeat settings |
+| `entities update <id>` | Update properties, recipe, heartbeat |
 | `entities delete <id>` | Delete entity |
-| `contexts list` | List contexts |
-| `contexts create <name>` | Create a scoping context |
-| `contexts delete <id>` | Delete context |
 
 ### Intelligence
 | Command | Description |

package/bin/cli.js

@@ -19,6 +19,7 @@ import { recipesListCommand, recipesGetCommand, recipesCreateCommand, recipesDel
 import { relationshipTypesListCommand } from '../src/commands/relationship-types.js';
 import { docsListCommand, docsShowCommand } from '../src/commands/docs.js';
 import { registerRootsCommand } from '../src/commands/roots.js';
+import { registerCuriosityCommand } from '../src/commands/curiosity.js';
 
 program
   .name('trucontext')
@@ -136,6 +137,9 @@ entities.command('edges <entityId>')
 // Root Nodes
 registerRootsCommand(program);
 
+// Curiosity
+registerCuriosityCommand(program);
+
 // Recipes
 const recipes = program.command('recipes').description('Manage recipes').action(function() { this.help(); });
 recipes.command('list')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trucontext",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "TruContext CLI — contextual memory for AI applications",
   "type": "module",
   "bin": {

package/src/commands/curiosity.js

@@ -0,0 +1,97 @@
+// curiosity.js — Curiosity Engine commands
+//
+// Trigger curiosity analysis and view knowledge gaps for a root node.
+// Curiosity analysis is always scoped to a root node's ego network.
+
+import chalk from 'chalk';
+import { controlPlane } from '../client.js';
+import { getConfig, getActiveApp } from '../config.js';
+
+export function registerCuriosityCommand(program) {
+  const curiosity = program
+    .command('curiosity')
+    .description('Curiosity engine — discover knowledge gaps')
+    .action(function() { this.help(); });
+
+  // List curiosity packets
+  curiosity
+    .command('list')
+    .description('List curiosity packets for a root node')
+    .option('--root <rootId>', 'Root node ID (uses active root if not specified)')
+    .option('--status <status>', 'Filter by status: PENDING, DISMISSED', 'PENDING')
+    .option('--limit <n>', 'Max packets to return', '20')
+    .action(async (opts) => {
+      const appId = getActiveApp();
+      const config = getConfig();
+      const rootId = opts.root || config.activeRoot;
+      if (!rootId) {
+        console.error(chalk.red('No root specified. Use --root <id> or set active root with: trucontext roots use <id>'));
+        process.exit(1);
+      }
+
+      try {
+        const res = await controlPlane('GET', `/apps/${appId}/mind/curiosity?root_id=${rootId}&status=${opts.status}&limit=${opts.limit}`);
+        const packets = res.data?.packets || [];
+
+        if (packets.length === 0) {
+          console.log(chalk.dim(`No ${opts.status.toLowerCase()} curiosity packets for root: ${rootId}`));
+          return;
+        }
+
+        console.log(chalk.bold(`Curiosity Packets (${packets.length}) — root: ${rootId}\n`));
+        for (const p of packets) {
+          const typeColor = p.curiosity_type === 'EXTERNAL' ? chalk.cyan : chalk.yellow;
+          console.log(`  ${typeColor(`[${p.gap_type}]`)} ${p.question}`);
+          if (p.why_it_matters) console.log(chalk.dim(`    Why: ${p.why_it_matters}`));
+          if (p.suggested_approach) console.log(chalk.dim(`    Approach: ${p.suggested_approach}`));
+          console.log(chalk.dim(`    Priority: ${p.priority_score?.toFixed(2) || '?'} | Status: ${p.status} | ID: ${p.packet_id}`));
+          console.log();
+        }
+      } catch (err) {
+        console.error(chalk.red('Failed:'), err.response?.data?.error || err.message);
+        process.exit(1);
+      }
+    });
+
+  // Trigger on-demand curiosity evaluation
+  curiosity
+    .command('trigger')
+    .description('Run curiosity analysis on a root node')
+    .option('--root <rootId>', 'Root node ID (uses active root if not specified)')
+    .action(async (opts) => {
+      const appId = getActiveApp();
+      const config = getConfig();
+      const rootId = opts.root || config.activeRoot;
+      if (!rootId) {
+        console.error(chalk.red('No root specified. Use --root <id> or set active root with: trucontext roots use <id>'));
+        process.exit(1);
+      }
+
+      try {
+        console.log(chalk.dim(`Triggering curiosity analysis for root: ${rootId}...`));
+        await controlPlane('POST', `/apps/${appId}/mind/curiosity/trigger`, {
+          root_id: rootId,
+        });
+        console.log(chalk.green(`Curiosity analysis started for root: ${rootId}`));
+        console.log(chalk.dim(`Results will appear shortly. Check with: trucontext curiosity list --root ${rootId}`));
+      } catch (err) {
+        console.error(chalk.red('Failed:'), err.response?.data?.error || err.message);
+        process.exit(1);
+      }
+    });
+
+  // Dismiss a curiosity packet
+  curiosity
+    .command('dismiss <packetId>')
+    .description('Dismiss a curiosity packet')
+    .action(async (packetId) => {
+      const appId = getActiveApp();
+      try {
+        await controlPlane('PUT', `/apps/${appId}/mind/curiosity/${packetId}/dismiss`);
+        console.log(chalk.green(`Dismissed: ${packetId}`));
+      } catch (err) {
+        console.error(chalk.red('Failed:'), err.response?.data?.error || err.message);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/roots.js

@@ -20,7 +20,7 @@ export function registerRootsCommand(program) {
     .requiredOption('--id <entityId>', 'Unique identifier for the root node')
     .requiredOption('--type <type>', 'Node type (e.g., Person, Agent, Organization)')
     .requiredOption('--recipe <recipeId>', 'Recipe ID (e.g., recipe:personal-assistant-memory)')
-    .option('--dreamers <list>', 'Dreamers: "all" or comma-separated (e.g., decay,curiosity)', 'all')
+    .option('--dreamers <list>', 'Dreamers: "all" or comma-separated. Valid: decay, concepts, people, primitives, curiosity, entity-linking, consolidation, fitness', 'all')
     .option('--hop-depth <n>', 'Max traversal depth for ego network (default: unlimited)', parseInt)
     .option('--do-not-follow', 'Mark as structural root — do not traverse into from other roots')
     .option('--properties <json>', 'JSON properties object')
@@ -128,7 +128,7 @@ export function registerRootsCommand(program) {
     .command('update <rootId>')
     .description('Update a root node')
     .option('--recipe <recipeId>', 'New recipe ID')
-    .option('--dreamers <list>', 'New dreamers: "all" or comma-separated')
+    .option('--dreamers <list>', 'New dreamers: "all" or comma-separated. Valid: decay, concepts, people, primitives, curiosity, entity-linking, consolidation, fitness')
     .option('--hop-depth <n>', 'New hop depth', parseInt)
     .option('--do-not-follow', 'Set do-not-follow flag')
     .option('--no-do-not-follow', 'Clear do-not-follow flag')