trucontext 0.6.0 → 0.7.1

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/package.json

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

package/src/commands/entities.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
-import { dataPlane } from '../client.js';
+import { controlPlane } from '../client.js';
+import { getActiveApp } from '../config.js';
 
 // Fields stored on the node but not user-declared properties
 const SYSTEM_FIELDS = new Set([
@@ -38,15 +39,16 @@ function displayEntity(e) {
 
 export async function entitiesListCommand(options) {
   try {
+    const appId = getActiveApp();
     const params = new URLSearchParams();
     if (options.type) params.set('type', options.type);
     if (options.context) params.set('context_id', options.context);
     if (options.scope) params.set('scope', options.scope);
     if (options.limit) params.set('limit', options.limit);
     const qs = params.toString();
-    const path = `/v1/entities${qs ? `?${qs}` : ''}`;
+    const path = `/apps/${appId}/entities${qs ? `?${qs}` : ''}`;
 
-    const res = await dataPlane('GET', path);
+    const res = await controlPlane('GET', path);
     const entities = Array.isArray(res.data) ? res.data : (res.data?.entities || []);
 
     if (entities.length === 0) {
@@ -66,13 +68,14 @@ export async function entitiesListCommand(options) {
 
 export async function entitiesGetCommand(entityId) {
   try {
-    const res = await dataPlane('GET', `/v1/entities/${entityId}`);
+    const appId = getActiveApp();
+    const res = await controlPlane('GET', `/apps/${appId}/entities/${entityId}`);
     const e = res.data || res;
     displayEntity(e);
 
     // Show edges if available
     try {
-      const edgeRes = await dataPlane('GET', `/v1/entities/${entityId}/edges`);
+      const edgeRes = await controlPlane('GET', `/apps/${appId}/entities/${entityId}/edges`);
       const edges = edgeRes.data?.edges || edgeRes.data || [];
       if (edges.length > 0) {
         console.log(chalk.dim(`\n  Edges (${edges.length}):`));
@@ -101,6 +104,7 @@ export async function entitiesCreateCommand(options) {
       process.exit(1);
     }
 
+    const appId = getActiveApp();
     const body = {
       entityId: options.id,
       type: options.type,
@@ -133,7 +137,7 @@ export async function entitiesCreateCommand(options) {
       });
     }
 
-    const res = await dataPlane('POST', '/v1/entities', body);
+    const res = await controlPlane('POST', `/apps/${appId}/entities`, body);
     const e = res.data || res;
     console.log(chalk.green(`Created: ${chalk.bold(e.entityId || options.id)}`));
   } catch (err) {
@@ -144,6 +148,7 @@ export async function entitiesCreateCommand(options) {
 
 export async function entitiesUpdateCommand(entityId, options) {
   try {
+    const appId = getActiveApp();
     const body = {};
 
     if (options.properties) {
@@ -173,7 +178,7 @@ export async function entitiesUpdateCommand(entityId, options) {
       });
     }
 
-    await dataPlane('PUT', `/v1/entities/${entityId}`, body);
+    await controlPlane('PUT', `/apps/${appId}/entities/${entityId}`, body);
     console.log(chalk.green(`Updated: ${entityId}`));
   } catch (err) {
     console.error(chalk.red(`Failed: ${err.message}`));
@@ -183,7 +188,8 @@ export async function entitiesUpdateCommand(entityId, options) {
 
 export async function entitiesDeleteCommand(entityId) {
   try {
-    await dataPlane('DELETE', `/v1/entities/${entityId}`);
+    const appId = getActiveApp();
+    await controlPlane('DELETE', `/apps/${appId}/entities/${entityId}`);
     console.log(chalk.green(`Deleted: ${entityId}`));
   } catch (err) {
     console.error(chalk.red(`Failed: ${err.message}`));
@@ -193,7 +199,8 @@ export async function entitiesDeleteCommand(entityId) {
 
 export async function entitiesEdgesCommand(entityId) {
   try {
-    const res = await dataPlane('GET', `/v1/entities/${entityId}/edges`);
+    const appId = getActiveApp();
+    const res = await controlPlane('GET', `/apps/${appId}/entities/${entityId}/edges`);
     const edges = res.data?.edges || res.data || [];
 
     if (edges.length === 0) {

package/src/commands/ingest.js

@@ -1,10 +1,12 @@
 import chalk from 'chalk';
 import { readFileSync, existsSync } from 'fs';
 import { basename } from 'path';
-import { dataPlane } from '../client.js';
+import { controlPlane } from '../client.js';
+import { getActiveApp } from '../config.js';
 
 export async function ingestCommand(source, options) {
   try {
+    const appId = getActiveApp();
     let body;
 
     if (existsSync(source)) {
@@ -50,11 +52,12 @@ export async function ingestCommand(source, options) {
       };
     });
 
-    const res = await dataPlane('POST', '/v1/ingest', body);
+    const res = await controlPlane('POST', `/apps/${appId}/ingest`, body);
+    const data = res.data || res;
     console.log(chalk.green('Accepted'));
-    console.log(chalk.dim(`Content ID: ${res.contentId}`));
-    if (res.status === 'upload_required') {
-      console.log(chalk.yellow(`Large file — upload to: ${res.uploadUrl}`));
+    console.log(chalk.dim(`Content ID: ${data.contentId}`));
+    if (data.status === 'upload_required') {
+      console.log(chalk.yellow(`Large file — upload to: ${data.uploadUrl}`));
     }
   } catch (err) {
     console.error(chalk.red(`Ingest failed: ${err.message}`));

package/src/commands/init.js

@@ -105,7 +105,7 @@ export async function initCommand(name, options) {
     const rootName = await input({ message: 'Display name (e.g., Dustin Henderson):' });
 
     try {
-      await controlPlane('POST', '/roots', {
+      await controlPlane('POST', `/apps/${app.appId}/roots`, {
         entityId: rootId,
         type: rootType,
         recipe_id: rootRecipe,

package/src/commands/query.js

@@ -1,9 +1,11 @@
 import chalk from 'chalk';
-import { dataPlane } from '../client.js';
-import { getConfig } from '../config.js';
+import { controlPlane } from '../client.js';
+import { getConfig, getActiveApp } from '../config.js';
 
 export async function queryCommand(question, options) {
   try {
+    const appId = getActiveApp();
+
     // root_id is required — from --root flag or active root
     const rootId = options.root || getConfig().activeRoot;
     if (!rootId) {
@@ -25,34 +27,35 @@ export async function queryCommand(question, options) {
 
     if (options.context) body.context_id = options.context;
 
-    const res = await dataPlane('POST', '/v1/query', body);
+    const res = await controlPlane('POST', `/apps/${appId}/mind/query`, body);
+    const data = res.data || res;
 
     // Print answer
-    if (res.answer?.summary) {
+    if (data.answer?.summary) {
       console.log(chalk.bold('\nAnswer:'));
-      console.log(res.answer.summary);
-      if (res.answer.confidence) {
-        console.log(chalk.dim(`\nConfidence: ${(res.answer.confidence * 100).toFixed(0)}%`));
+      console.log(data.answer.summary);
+      if (data.answer.confidence) {
+        console.log(chalk.dim(`\nConfidence: ${(data.answer.confidence * 100).toFixed(0)}%`));
       }
     }
 
     // Print concepts
-    if (res.concepts?.length > 0) {
+    if (data.concepts?.length > 0) {
       console.log(chalk.bold('\nConcepts:'));
-      for (const c of res.concepts.slice(0, 5)) {
+      for (const c of data.concepts.slice(0, 5)) {
         console.log(`  ${c.label} ${chalk.dim(`(${c.evidence_count} evidence)`)}`);
       }
     }
 
     // Print people
-    if (res.people?.length > 0) {
+    if (data.people?.length > 0) {
       console.log(chalk.bold('\nPeople:'));
-      for (const p of res.people.slice(0, 5)) {
+      for (const p of data.people.slice(0, 5)) {
         console.log(`  ${p.name} ${chalk.dim(p.relationship || '')}`);
       }
     }
 
-    console.log(chalk.dim(`\n${res.latency_ms}ms`));
+    console.log(chalk.dim(`\n${data.latency_ms}ms`));
   } catch (err) {
     console.error(chalk.red(`Query failed: ${err.message}`));
     process.exit(1);

package/src/commands/recall.js

@@ -1,9 +1,11 @@
 import chalk from 'chalk';
-import { dataPlane } from '../client.js';
-import { getConfig } from '../config.js';
+import { controlPlane } from '../client.js';
+import { getConfig, getActiveApp } from '../config.js';
 
 export async function recallCommand(query, options) {
   try {
+    const appId = getActiveApp();
+
     // root_id is required — from --root flag or active root
     const rootId = options.root || getConfig().activeRoot;
     if (!rootId) {
@@ -20,18 +22,19 @@ export async function recallCommand(query, options) {
 
     if (options.context) body.context_id = options.context;
 
-    const res = await dataPlane('POST', '/v1/recall', body);
+    const res = await controlPlane('POST', `/apps/${appId}/recall`, body);
+    const data = res.data || res;
 
     // Print synthesis
-    if (res.synthesis?.summary) {
+    if (data.synthesis?.summary) {
       console.log(chalk.bold('\nSynthesis:'));
-      console.log(res.synthesis.summary);
+      console.log(data.synthesis.summary);
     }
 
     // Print seeds
-    if (res.seeds?.length > 0) {
-      console.log(chalk.bold(`\nSeeds (${res.seeds.length}):`));
-      for (const s of res.seeds) {
+    if (data.seeds?.length > 0) {
+      console.log(chalk.bold(`\nSeeds (${data.seeds.length}):`));
+      for (const s of data.seeds) {
         const label = s.snippet || s.label || s.id;
         const score = (s.score * 100).toFixed(0);
         console.log(`  ${chalk.dim(`${score}%`)} ${label.slice(0, 100)}`);
@@ -39,11 +42,11 @@ export async function recallCommand(query, options) {
     }
 
     // Print graph context summary
-    if (res.context) {
-      console.log(chalk.dim(`\nGraph: ${res.context.nodes?.length || 0} nodes, ${res.context.edges?.length || 0} edges`));
+    if (data.context) {
+      console.log(chalk.dim(`\nGraph: ${data.context.nodes?.length || 0} nodes, ${data.context.edges?.length || 0} edges`));
     }
 
-    console.log(chalk.dim(`${res.latency_ms}ms`));
+    console.log(chalk.dim(`${data.latency_ms}ms`));
   } catch (err) {
     console.error(chalk.red(`Recall failed: ${err.message}`));
     process.exit(1);

package/src/commands/roots.js

@@ -5,7 +5,7 @@
 
 import chalk from 'chalk';
 import { controlPlane } from '../client.js';
-import { getConfig, saveConfig } from '../config.js';
+import { getConfig, saveConfig, getActiveApp } from '../config.js';
 
 export function registerRootsCommand(program) {
   const roots = program
@@ -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')
@@ -54,7 +54,8 @@ export function registerRootsCommand(program) {
           });
         }
 
-        const res = await controlPlane('POST', '/roots', body);
+        const appId = getActiveApp();
+        const res = await controlPlane('POST', `/apps/${appId}/roots`, body);
         const r = res.data;
         console.log(chalk.green(`Root node created: ${r.entityId}`));
         console.log(`  Type: ${r.type}`);
@@ -73,7 +74,8 @@ export function registerRootsCommand(program) {
     .description('List all root nodes for the active app')
     .action(async () => {
       try {
-        const res = await controlPlane('GET', '/roots');
+        const appId = getActiveApp();
+        const res = await controlPlane('GET', `/apps/${appId}/roots`);
         const rootNodes = res.data?.roots || [];
         if (rootNodes.length === 0) {
           console.log('No root nodes. Create one with: trucontext roots create');
@@ -99,7 +101,8 @@ export function registerRootsCommand(program) {
     .description('Show details of a root node')
     .action(async (rootId) => {
       try {
-        const res = await controlPlane('GET', `/roots/${rootId}`);
+        const appId = getActiveApp();
+        const res = await controlPlane('GET', `/apps/${appId}/roots/${rootId}`);
         const r = res.data;
         console.log(chalk.bold(`Root: ${r.entityId}`));
         console.log(`  Type: ${r.type}`);
@@ -125,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')
@@ -144,7 +147,8 @@ export function registerRootsCommand(program) {
           }
         }
 
-        await controlPlane('PUT', `/roots/${rootId}`, body);
+        const appId = getActiveApp();
+        await controlPlane('PUT', `/apps/${appId}/roots/${rootId}`, body);
         console.log(chalk.green(`Updated: ${rootId}`));
       } catch (err) {
         console.error(chalk.red('Failed:'), err.response?.data?.error || err.message);
@@ -158,7 +162,8 @@ export function registerRootsCommand(program) {
     .description('Demote a root node to a regular entity (does not delete the node)')
     .action(async (rootId) => {
       try {
-        await controlPlane('DELETE', `/roots/${rootId}`);
+        const appId = getActiveApp();
+        await controlPlane('DELETE', `/apps/${appId}/roots/${rootId}`);
         console.log(chalk.green(`Demoted: ${rootId} (no longer a root node)`));
 
         const config = getConfig();
@@ -178,7 +183,8 @@ export function registerRootsCommand(program) {
     .description('Set the active root node for queries and recall')
     .action(async (rootId) => {
       try {
-        await controlPlane('GET', `/roots/${rootId}`);
+        const appId = getActiveApp();
+        await controlPlane('GET', `/apps/${appId}/roots/${rootId}`);
         const config = getConfig();
         config.activeRoot = rootId;
         saveConfig(config);