novyx 2.9.1 → 2.10.0

package/README.md

@@ -1,6 +1,6 @@
 # Novyx SDK for JavaScript / TypeScript
 
-Persistent memory, rollback, and audit trail for AI agents.
+**Persistent memory + rollback + audit trail for AI agents.** Give your AI persistent memory, semantic search, Magic Rollback to undo mistakes, cryptographic audit trails, context spaces for multi-agent collaboration, replay for time-travel debugging, and cortex for autonomous memory intelligence.
 
 ## Installation
 
@@ -16,22 +16,210 @@ import { Novyx } from "novyx";
 const nx = new Novyx({ apiKey: "nram_your_key_here" });
 
 // Store a memory
-await nx.remember("User prefers dark mode", { tags: ["ui", "prefs"], importance: 8 });
+await nx.remember("User prefers dark mode and async communication", {
+  tags: ["preferences"],
+  importance: 8,
+});
 
-// Search semantically
-const results = await nx.recall("user preferences");
+// Search memories semantically
+const results = await nx.recall("communication style", { limit: 5 });
 for (const mem of results.memories) {
   console.log(`${mem.observation} (score: ${mem.score})`);
 }
 
-// Get a specific memory
-const mem = await nx.memory("urn:uuid:...");
+// Check audit trail
+const audit = await nx.audit({ limit: 10 });
 
-// Delete a memory
-await nx.forget("urn:uuid:...");
+// Magic Rollback — undo to any point in time (Pro+)
+await nx.rollback("2 hours ago");
 ```
 
-## Sessions
+## Complete Lifecycle Example
+
+```typescript
+import { Novyx } from "novyx";
+
+const nx = new Novyx({ apiKey: "nram_your_key_here" });
+
+// 1. Store memories
+await nx.remember("User mentioned budget is $50K for Q1", {
+  tags: ["sales", "budget"],
+  importance: 8,
+});
+await nx.remember("User prefers email over phone calls", {
+  tags: ["preferences"],
+  importance: 7,
+});
+await nx.remember("User is building a real estate AI assistant", {
+  tags: ["project"],
+});
+
+// 2. Semantic search
+const results = await nx.recall("what is the user's budget?", { limit: 3 });
+console.log(`Found: ${results.memories[0].observation}`);
+
+// 3. Check audit trail
+const audit = await nx.audit({ limit: 5 });
+
+// 4. Preview rollback first, then execute (Pro+)
+const preview = await nx.rollbackPreview("1 hour ago");
+const result = await nx.rollback("1 hour ago");
+
+// 5. Trace agent actions (Pro+)
+const trace = await nx.traceCreate("sales-agent", "session-123");
+await nx.traceStep(trace.trace_id, "thought", "Analyzing budget", "User has $50K");
+await nx.traceStep(trace.trace_id, "action", "draft_proposal");
+const completed = await nx.traceComplete(trace.trace_id);
+```
+
+## Features
+
+### Persistent Memory
+
+Store observations about users, contexts, and decisions. Your AI remembers everything across sessions.
+
+```typescript
+// Store with full options
+await nx.remember("Customer mentioned budget is $50K for Q1", {
+  tags: ["sales", "budget"],
+  importance: 8,
+  metadata: { customer_id: "12345", quarter: "Q1" },
+  agent_id: "sales-agent",
+});
+
+// List all memories
+const list = await nx.list({ limit: 100, min_importance: 7 });
+console.log(`Found ${list.total_count} high-importance memories`);
+
+// Get specific memory
+const mem = await nx.memory("urn:uuid:abc123...");
+
+// Delete memory
+await nx.forget("urn:uuid:abc123...");
+
+// Get stats
+const stats = await nx.stats();
+```
+
+### Semantic Search
+
+Find relevant memories using natural language queries. No exact keyword matching required.
+
+```typescript
+const results = await nx.recall("what is the user working on?", { limit: 3 });
+// Returns: "User is building a real estate AI assistant"
+
+// Filter by tags
+const filtered = await nx.recall("budget constraints", {
+  tags: ["sales"],
+  limit: 5,
+  min_score: 0.5,
+});
+
+// Filter by agent
+const agentResults = await nx.recall("preferences", {
+  agents: ["sales-agent"],
+});
+```
+
+### Magic Rollback (Pro+)
+
+Made a mistake? Roll back your AI's memory to any point in time.
+
+```typescript
+// Preview rollback first
+const preview = await nx.rollbackPreview("2 hours ago");
+
+// Execute rollback
+const result = await nx.rollback("2 hours ago");
+
+// Rollback with options
+await nx.rollback("2 hours ago", { dryRun: true, preserveEvidence: true });
+
+// View rollback history
+const history = await nx.rollbackHistory(10);
+```
+
+### Cryptographic Audit Trail
+
+Every operation is logged with SHA-256 hashing for tamper-proof history.
+
+```typescript
+// Get recent audit entries
+const audit = await nx.audit({ limit: 50 });
+
+// Export audit log (Pro+)
+const csv = await nx.auditExport("csv");
+
+// Verify integrity
+const verification = await nx.auditVerify();
+console.log(`Valid: ${verification.valid}`);
+```
+
+### Trace Audit (Pro+)
+
+Track agent actions with RSA signatures and real-time policy enforcement.
+
+```typescript
+// Create trace session
+const trace = await nx.traceCreate("my-agent", "session-123");
+
+// Add steps
+await nx.traceStep(trace.trace_id, "thought", "Planning email");
+await nx.traceStep(trace.trace_id, "action", "send_email", undefined, {
+  to: "user@example.com",
+});
+await nx.traceStep(trace.trace_id, "observation", "Email sent successfully");
+
+// Finalize with RSA signature
+const result = await nx.traceComplete(trace.trace_id);
+
+// Verify integrity later
+const verification = await nx.traceVerify(trace.trace_id);
+```
+
+### Context Spaces (Multi-Agent)
+
+Create shared memory spaces for multi-agent collaboration with fine-grained permissions.
+
+```typescript
+// Share a tag with another user
+await nx.shareContext("project-notes", "colleague@example.com", "write");
+
+// List shared spaces
+const spaces = await nx.sharedContexts();
+
+// Accept a share invitation
+await nx.acceptSharedContext("token_abc123");
+
+// Store and recall in a space
+await nx.remember("Shared insight", { space_id: "cs_abc123", tags: ["shared"] });
+const results = await nx.recall("insights", { space_id: "cs_abc123" });
+
+// Revoke access
+await nx.revokeSharedContext("token_abc123");
+```
+
+### Knowledge Graph & Links
+
+Create relationships between memories — build a connected knowledge base.
+
+```typescript
+// Link two memories
+await nx.link("mem-1", "mem-2", { relation: "caused_by", weight: 0.9 });
+
+// Get links for a memory
+const linked = await nx.links("mem-1");
+console.log(linked.edges);
+
+// Remove a link
+await nx.unlink("mem-1", "mem-2", "caused_by");
+
+// Get full memory graph
+const graph = await nx.graph();
+```
+
+### Sessions
 
 Automatically tag and filter memories by session:
 
@@ -43,23 +231,73 @@ const results = await session.recall("billing");
 // Only returns memories from this session
 ```
 
-## Links / Graph
+### Replay — Time-Travel Debugging (Pro+)
 
-Create relationships between memories:
+Inspect how your agent's memory changed over time.
 
 ```typescript
-await nx.link("mem-1", "mem-2", { relation: "caused_by", weight: 0.9 });
+// Timeline of operations
+const timeline = await nx.replayTimeline({
+  since: "2026-01-01T00:00:00Z",
+  limit: 50,
+});
+for (const entry of timeline.entries) {
+  console.log(`${entry.timestamp} - ${entry.operation}`);
+}
 
-const linked = await nx.links("mem-1");
-console.log(linked.edges);
+// Point-in-time snapshot
+const snapshot = await nx.replaySnapshot("2026-01-15T10:00:00Z");
+console.log(`${snapshot.total_memories} memories at that point`);
 
-await nx.unlink("mem-1", "mem-2", "caused_by");
+// Full lifecycle of a memory
+const lifecycle = await nx.replayMemory("urn:uuid:abc123...");
+
+// Diff between two timestamps
+const diff = await nx.replayDiff("2026-01-01T00:00:00Z", "2026-01-15T00:00:00Z");
+console.log(`Added: ${diff.summary.added}, Removed: ${diff.summary.removed}`);
+
+// Counterfactual recall — what would the agent have recalled? (Enterprise)
+const recall = await nx.replayRecall("user preferences", "2026-01-10T00:00:00Z");
+
+// Memory composition drift (Enterprise)
+const drift = await nx.replayDrift("2026-01-01T00:00:00Z", "2026-02-01T00:00:00Z");
+```
+
+### Cortex — Autonomous Memory Intelligence (Pro+)
+
+Your memory gets smarter on its own. Cortex consolidates near-duplicates, boosts frequently-recalled memories, decays forgotten ones, and generates insights.
+
+```typescript
+// Check cortex status
+const status = await nx.cortexStatus();
+console.log(`Enabled: ${status.enabled}, Last run: ${status.last_run_at}`);
+
+// Configure cortex
+await nx.cortexUpdateConfig({
+  consolidation_enabled: true,
+  consolidation_threshold: 0.9,
+  decay_age_days: 30,
+});
+
+// Trigger a manual cycle
+const result = await nx.cortexRun();
+console.log(
+  `Consolidated: ${result.consolidated}, Boosted: ${result.boosted}, Decayed: ${result.decayed}`
+);
+
+// Get insights (Enterprise)
+const insights = await nx.cortexInsights({ limit: 10 });
+for (const insight of insights.insights) {
+  console.log(`Insight: ${insight.observation}`);
+}
 ```
 
 ## API Reference
 
+### Memory Methods
+
 | Method | Description |
-|---|---|
+|--------|-------------|
 | `remember(observation, opts?)` | Store a memory |
 | `recall(query, opts?)` | Semantic search |
 | `memories(opts?)` | List memories (raw) |
@@ -68,33 +306,92 @@ await nx.unlink("mem-1", "mem-2", "caused_by");
 | `delete(id)` | Alias for forget |
 | `list(opts?)` | List memories (ListResult) |
 | `stats()` | Memory statistics |
-| `shareContext(tag, email, permission?)` | Share a context space |
-| `acceptSharedContext(token)` | Join a shared space |
-| `sharedContexts()` | List shared spaces |
-| `revokeSharedContext(token)` | Revoke a share |
-| `graph(opts?)` | Get memory graph |
-| `rollback(target, dryRun?, preserveEvidence?)` | Rollback memories |
-| `rollbackPreview(target)` | Preview rollback |
+| `supersede(oldId, newId)` | Mark a memory as superseded |
+
+### Rollback Methods (Pro+)
+
+| Method | Description |
+|--------|-------------|
+| `rollback(target, opts?)` | Rollback to timestamp or relative time |
+| `rollbackPreview(target)` | Preview rollback changes |
 | `rollbackHistory(limit?)` | List past rollbacks |
-| `audit(opts?)` | Get audit trail |
-| `auditExport(format?)` | Export audit log |
+
+### Audit Methods
+
+| Method | Description |
+|--------|-------------|
+| `audit(opts?)` | Get audit entries |
+| `auditExport(format?)` | Export audit log (Pro+) |
 | `auditVerify()` | Verify audit integrity |
-| `traceCreate(agentId, sessionId?, metadata?)` | Create trace |
+
+### Trace Methods (Pro+)
+
+| Method | Description |
+|--------|-------------|
+| `traceCreate(agentId, sessionId?, metadata?)` | Create trace session |
 | `traceStep(traceId, stepType, name, content?, attrs?)` | Add trace step |
-| `traceComplete(traceId)` | Complete trace |
-| `traceVerify(traceId)` | Verify trace |
+| `traceComplete(traceId)` | Finalize trace with RSA signature |
+| `traceVerify(traceId)` | Verify trace integrity |
+
+### Context Space Methods
+
+| Method | Description |
+|--------|-------------|
+| `shareContext(tag, email, permission?)` | Share a tag/space |
+| `acceptSharedContext(token)` | Accept share invitation |
+| `sharedContexts()` | List shared spaces |
+| `revokeSharedContext(token)` | Revoke a share |
+
+### Knowledge Graph & Link Methods
+
+| Method | Description |
+|--------|-------------|
+| `link(sourceId, targetId, opts?)` | Create a directed edge |
+| `unlink(sourceId, targetId, relation?)` | Remove a link |
+| `links(memoryId, relation?)` | Get memory links |
+| `graph(opts?)` | Get memory graph |
+
+### Replay Methods (Pro+)
+
+| Method | Description |
+|--------|-------------|
+| `replayTimeline(opts?)` | Timeline of memory operations |
+| `replaySnapshot(at, opts?)` | Reconstruct memory state at timestamp |
+| `replayMemory(memoryId)` | Full lifecycle of a single memory |
+| `replayDiff(from, to)` | Diff between two timestamps |
+| `replayRecall(query, at, opts?)` | Counterfactual recall (Enterprise) |
+| `replayDrift(from, to)` | Memory composition drift (Enterprise) |
+
+### Cortex Methods (Pro+)
+
+| Method | Description |
+|--------|-------------|
+| `cortexStatus()` | Get cortex status, last run, and config |
+| `cortexConfig()` | Get current cortex configuration |
+| `cortexUpdateConfig(updates)` | Update cortex settings |
+| `cortexRun()` | Trigger a manual cortex cycle |
+| `cortexInsights(opts?)` | Get generated insights (Enterprise) |
+
+### Session & Utility Methods
+
+| Method | Description |
+|--------|-------------|
+| `session(sessionId)` | Create session scope |
+| `contextNow()` | Get temporal context snapshot |
 | `usage()` | Current usage stats |
 | `plans()` | Available plans |
 | `health()` | API health check |
-| `session(sessionId)` | Create session scope |
-| `link(sourceId, targetId, opts?)` | Link two memories |
-| `unlink(sourceId, targetId, relation?)` | Remove a link |
-| `links(memoryId, relation?)` | Get memory links |
 
 ## Error Handling
 
 ```typescript
-import { Novyx, NovyxAuthError, NovyxForbiddenError, NovyxRateLimitError } from "novyx";
+import {
+  Novyx,
+  NovyxAuthError,
+  NovyxForbiddenError,
+  NovyxRateLimitError,
+  NovyxNotFoundError,
+} from "novyx";
 
 try {
   await nx.rollback("2 hours ago");
@@ -104,10 +401,30 @@ try {
     console.log(`Upgrade at: ${err.upgradeUrl}`);
   } else if (err instanceof NovyxRateLimitError) {
     console.log(`Limit: ${err.limitType}, retry in ${err.retryAfter}s`);
+  } else if (err instanceof NovyxNotFoundError) {
+    console.log("Memory not found");
+  } else if (err instanceof NovyxAuthError) {
+    console.log("Invalid API key");
   }
 }
 ```
 
+## Pricing
+
+| Tier | Price | Memories | API Calls | Rollbacks | Audit | Features |
+|------|-------|----------|-----------|-----------|-------|----------|
+| **Free** | $0 | 5,000 | 5,000/mo | 10/month | 7 days | Basic memory, LWW conflict resolution |
+| **Starter** | $12/mo | 25,000 | 25,000/mo | 30/month | 14 days | + All conflict strategies |
+| **Pro** | $39/mo | Unlimited | 100,000/mo | Unlimited | 30 days | + Replay, Cortex, traces, knowledge graph |
+| **Enterprise** | $199/mo | Unlimited | Unlimited | Unlimited | 90 days | + Cortex insights, counterfactual recall, drift analysis |
+
+## Links
+
+- [API Documentation](https://novyx-ram-api.fly.dev/docs)
+- [Endpoint Reference](https://github.com/novyx-labs/novyx-core/blob/main/ENDPOINTS.md)
+- [Pricing](https://novyxlabs.com/pricing)
+- [Get API Key](https://novyxlabs.com)
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -273,11 +273,13 @@ declare class Novyx {
         tags?: string[];
         context?: string;
         importance?: number;
+        confidence?: number;
         agent_id?: string;
         space_id?: string;
         metadata?: Record<string, any>;
         ttl_seconds?: number;
         auto_link?: boolean;
+        conflict_strategy?: "reject" | "lww" | "merge";
     }): Promise<Record<string, any>>;
     recall(query: string, opts?: {
         limit?: number;
@@ -339,6 +341,7 @@ declare class Novyx {
     traceComplete(traceId: string): Promise<Record<string, any>>;
     traceVerify(traceId: string): Promise<Record<string, any>>;
     usage(): Promise<Record<string, any>>;
+    dashboard(): Promise<Record<string, any>>;
     plans(): Promise<Record<string, any>[]>;
     health(): Promise<Record<string, any>>;
     session(sessionId: string): NovyxSession;

package/dist/index.d.ts

@@ -273,11 +273,13 @@ declare class Novyx {
         tags?: string[];
         context?: string;
         importance?: number;
+        confidence?: number;
         agent_id?: string;
         space_id?: string;
         metadata?: Record<string, any>;
         ttl_seconds?: number;
         auto_link?: boolean;
+        conflict_strategy?: "reject" | "lww" | "merge";
     }): Promise<Record<string, any>>;
     recall(query: string, opts?: {
         limit?: number;
@@ -339,6 +341,7 @@ declare class Novyx {
     traceComplete(traceId: string): Promise<Record<string, any>>;
     traceVerify(traceId: string): Promise<Record<string, any>>;
     usage(): Promise<Record<string, any>>;
+    dashboard(): Promise<Record<string, any>>;
     plans(): Promise<Record<string, any>[]>;
     health(): Promise<Record<string, any>>;
     session(sessionId: string): NovyxSession;

package/dist/index.js

@@ -210,6 +210,7 @@ var Novyx = class {
       tags: opts?.tags ?? [],
       importance: opts?.importance ?? 5
     };
+    if (opts?.confidence !== void 0) body.confidence = opts.confidence;
     if (resolvedAgentId) body.agent_id = resolvedAgentId;
     if (opts?.space_id) body.space_id = opts.space_id;
     if (opts?.ttl_seconds !== void 0) body.ttl_seconds = opts.ttl_seconds;
@@ -219,7 +220,9 @@ var Novyx = class {
     } else if (opts?.metadata) {
       body.context = JSON.stringify(opts.metadata);
     }
-    return this._request("POST", "/v1/memories", { body });
+    const params = {};
+    if (opts?.conflict_strategy) params.conflict_strategy = opts.conflict_strategy;
+    return this._request("POST", "/v1/memories", { body, params: Object.keys(params).length ? params : void 0 });
   }
   async recall(query, opts) {
     const params = {
@@ -389,6 +392,9 @@ var Novyx = class {
   async usage() {
     return this._request("GET", "/v1/usage");
   }
+  async dashboard() {
+    return this._request("GET", "/v1/dashboard");
+  }
   async plans() {
     return this._request("GET", "/v1/plans");
   }

package/dist/index.mjs

@@ -177,6 +177,7 @@ var Novyx = class {
       tags: opts?.tags ?? [],
       importance: opts?.importance ?? 5
     };
+    if (opts?.confidence !== void 0) body.confidence = opts.confidence;
     if (resolvedAgentId) body.agent_id = resolvedAgentId;
     if (opts?.space_id) body.space_id = opts.space_id;
     if (opts?.ttl_seconds !== void 0) body.ttl_seconds = opts.ttl_seconds;
@@ -186,7 +187,9 @@ var Novyx = class {
     } else if (opts?.metadata) {
       body.context = JSON.stringify(opts.metadata);
     }
-    return this._request("POST", "/v1/memories", { body });
+    const params = {};
+    if (opts?.conflict_strategy) params.conflict_strategy = opts.conflict_strategy;
+    return this._request("POST", "/v1/memories", { body, params: Object.keys(params).length ? params : void 0 });
   }
   async recall(query, opts) {
     const params = {
@@ -356,6 +359,9 @@ var Novyx = class {
   async usage() {
     return this._request("GET", "/v1/usage");
   }
+  async dashboard() {
+    return this._request("GET", "/v1/dashboard");
+  }
   async plans() {
     return this._request("GET", "/v1/plans");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "novyx",
-  "version": "2.9.1",
+  "version": "2.10.0",
   "description": "Novyx SDK - Persistent memory, rollback, and audit trail for AI agents",
   "main": "dist/index.js",
   "module": "dist/index.mjs",