novyx 2.2.0

package/README.md

@@ -0,0 +1,113 @@
+# Novyx SDK for JavaScript / TypeScript
+
+Persistent memory, rollback, and audit trail for AI agents.
+
+## Installation
+
+```bash
+npm install novyx
+```
+
+## Quick Start
+
+```typescript
+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 });
+
+// Search semantically
+const results = await nx.recall("user preferences");
+for (const mem of results.memories) {
+  console.log(`${mem.observation} (score: ${mem.score})`);
+}
+
+// Get a specific memory
+const mem = await nx.memory("urn:uuid:...");
+
+// Delete a memory
+await nx.forget("urn:uuid:...");
+```
+
+## Sessions
+
+Automatically tag and filter memories by session:
+
+```typescript
+const session = nx.session("chat-abc123");
+
+await session.remember("User asked about billing");
+const results = await session.recall("billing");
+// Only returns memories from this session
+```
+
+## Links / Graph
+
+Create relationships between memories:
+
+```typescript
+await nx.link("mem-1", "mem-2", { relation: "caused_by", weight: 0.9 });
+
+const linked = await nx.links("mem-1");
+console.log(linked.edges);
+
+await nx.unlink("mem-1", "mem-2", "caused_by");
+```
+
+## API Reference
+
+| Method | Description |
+|---|---|
+| `remember(observation, opts?)` | Store a memory |
+| `recall(query, opts?)` | Semantic search |
+| `memories(opts?)` | List memories (raw) |
+| `memory(id)` | Get memory by ID |
+| `forget(id)` | Delete a memory |
+| `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 |
+| `rollbackHistory(limit?)` | List past rollbacks |
+| `audit(opts?)` | Get audit trail |
+| `auditExport(format?)` | Export audit log |
+| `auditVerify()` | Verify audit integrity |
+| `traceCreate(agentId, sessionId?, metadata?)` | Create trace |
+| `traceStep(traceId, stepType, name, content?, attrs?)` | Add trace step |
+| `traceComplete(traceId)` | Complete trace |
+| `traceVerify(traceId)` | Verify trace |
+| `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";
+
+try {
+  await nx.rollback("2 hours ago");
+} catch (err) {
+  if (err instanceof NovyxForbiddenError) {
+    console.log(`Upgrade required: ${err.requiredPlan}`);
+    console.log(`Upgrade at: ${err.upgradeUrl}`);
+  } else if (err instanceof NovyxRateLimitError) {
+    console.log(`Limit: ${err.limitType}, retry in ${err.retryAfter}s`);
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,202 @@
+interface Memory {
+    uuid: string;
+    observation: string;
+    context?: string;
+    agent_id?: string;
+    tags: string[];
+    importance: number;
+    confidence: number;
+    created_at: string;
+    score?: number;
+    similarity?: number;
+    vector_clock?: Record<string, number>;
+    conflict_metadata?: Record<string, any>;
+    expires_at?: string;
+}
+interface SearchResult {
+    query: string;
+    total_results: number;
+    memories: Memory[];
+}
+interface ListResult {
+    total_count: number;
+    memories: Memory[];
+    filters: Record<string, any>;
+}
+interface NovyxConfig {
+    apiKey: string;
+    apiUrl?: string;
+    timeout?: number;
+    agentId?: string;
+}
+interface Edge {
+    edge_id: string;
+    source_id: string;
+    target_id: string;
+    relation: string;
+    weight: number;
+    metadata: Record<string, any>;
+    created_at: string;
+}
+interface LinksResult {
+    memory_id: string;
+    edges: Edge[];
+    total: number;
+}
+
+declare class NovyxSession {
+    private client;
+    private sessionTag;
+    constructor(client: Novyx, sessionId: string);
+    remember(observation: string, opts?: {
+        tags?: string[];
+        context?: string;
+        importance?: number;
+        agent_id?: string;
+        space_id?: string;
+        metadata?: Record<string, any>;
+        ttl_seconds?: number;
+    }): Promise<Record<string, any>>;
+    recall(query: string, opts?: {
+        limit?: number;
+        tags?: string[];
+        min_score?: number;
+        scope?: string;
+        agents?: string[];
+        include_shared?: boolean;
+        space_id?: string;
+    }): Promise<SearchResult>;
+    memories(opts?: {
+        limit?: number;
+        offset?: number;
+        tags?: string[];
+        min_importance?: number;
+        include_shared?: boolean;
+        agent_id?: string;
+        space_id?: string;
+    }): Promise<Memory[]>;
+    list(opts?: {
+        limit?: number;
+        offset?: number;
+        tags?: string[];
+        min_importance?: number;
+        include_shared?: boolean;
+        agent_id?: string;
+        space_id?: string;
+    }): Promise<ListResult>;
+}
+
+declare class Novyx {
+    private apiKey;
+    private apiUrl;
+    private timeout;
+    private agentId?;
+    constructor(config: NovyxConfig);
+    private _validateKey;
+    private _request;
+    remember(observation: string, opts?: {
+        tags?: string[];
+        context?: string;
+        importance?: number;
+        agent_id?: string;
+        space_id?: string;
+        metadata?: Record<string, any>;
+        ttl_seconds?: number;
+    }): Promise<Record<string, any>>;
+    recall(query: string, opts?: {
+        limit?: number;
+        tags?: string[];
+        min_score?: number;
+        scope?: string;
+        agents?: string[];
+        include_shared?: boolean;
+        space_id?: string;
+    }): Promise<SearchResult>;
+    memories(opts?: {
+        limit?: number;
+        offset?: number;
+        tags?: string[];
+        min_importance?: number;
+        include_shared?: boolean;
+        agent_id?: string;
+        space_id?: string;
+    }): Promise<Memory[]>;
+    memory(memoryId: string): Promise<Memory>;
+    forget(memoryId: string): Promise<boolean>;
+    delete(memoryId: string): Promise<boolean>;
+    list(opts?: {
+        limit?: number;
+        offset?: number;
+        tags?: string[];
+        min_importance?: number;
+        include_shared?: boolean;
+        agent_id?: string;
+        space_id?: string;
+    }): Promise<ListResult>;
+    stats(): Promise<Record<string, any>>;
+    shareContext(tag: string, toEmail: string, permission?: string): Promise<Record<string, any>>;
+    acceptSharedContext(token: string): Promise<Record<string, any>>;
+    sharedContexts(): Promise<Record<string, any>>;
+    revokeSharedContext(token: string): Promise<Record<string, any>>;
+    graph(opts?: {
+        include_shared?: boolean;
+        agents?: string[];
+    }): Promise<Record<string, any>>;
+    rollback(target: string, dryRun?: boolean, preserveEvidence?: boolean): Promise<Record<string, any>>;
+    rollbackPreview(target: string): Promise<Record<string, any>>;
+    rollbackHistory(limit?: number): Promise<Record<string, any>[]>;
+    audit(opts?: {
+        limit?: number;
+        since?: string;
+        until?: string;
+        operation?: string;
+        artifact_id?: string;
+    }): Promise<Record<string, any>[]>;
+    auditExport(format?: string): Promise<Response>;
+    auditVerify(): Promise<Record<string, any>>;
+    traceCreate(agentId: string, sessionId?: string, metadata?: Record<string, any>): Promise<Record<string, any>>;
+    traceStep(traceId: string, stepType: string, name: string, content?: string, attributes?: Record<string, any>): Promise<Record<string, any>>;
+    traceComplete(traceId: string): Promise<Record<string, any>>;
+    traceVerify(traceId: string): Promise<Record<string, any>>;
+    usage(): Promise<Record<string, any>>;
+    plans(): Promise<Record<string, any>[]>;
+    health(): Promise<Record<string, any>>;
+    session(sessionId: string): NovyxSession;
+    link(sourceId: string, targetId: string, opts?: {
+        relation?: string;
+        weight?: number;
+        metadata?: Record<string, any>;
+    }): Promise<Record<string, any>>;
+    unlink(sourceId: string, targetId: string, relation?: string): Promise<Record<string, any>>;
+    links(memoryId: string, relation?: string): Promise<LinksResult>;
+}
+
+declare class NovyxError extends Error {
+    constructor(message: string);
+}
+declare class NovyxAuthError extends NovyxError {
+    constructor(message?: string);
+}
+declare class NovyxForbiddenError extends NovyxError {
+    data: Record<string, any>;
+    feature?: string;
+    requiredPlan?: string;
+    upgradeUrl?: string;
+    constructor(message?: string, data?: Record<string, any>);
+}
+declare class NovyxRateLimitError extends NovyxError {
+    data: Record<string, any>;
+    limitType?: string;
+    current?: number;
+    limit?: number;
+    retryAfter?: number;
+    constructor(message?: string, data?: Record<string, any>);
+}
+declare class NovyxNotFoundError extends NovyxError {
+    constructor(message?: string);
+}
+declare class NovyxSecurityError extends NovyxError {
+    constructor(message?: string);
+}
+
+export { type Edge, type LinksResult, type ListResult, type Memory, Novyx, NovyxAuthError, type NovyxConfig, NovyxError, NovyxForbiddenError, NovyxNotFoundError, NovyxRateLimitError, NovyxSecurityError, NovyxSession, type SearchResult };

package/dist/index.d.ts

@@ -0,0 +1,202 @@
+interface Memory {
+    uuid: string;
+    observation: string;
+    context?: string;
+    agent_id?: string;
+    tags: string[];
+    importance: number;
+    confidence: number;
+    created_at: string;
+    score?: number;
+    similarity?: number;
+    vector_clock?: Record<string, number>;
+    conflict_metadata?: Record<string, any>;
+    expires_at?: string;
+}
+interface SearchResult {
+    query: string;
+    total_results: number;
+    memories: Memory[];
+}
+interface ListResult {
+    total_count: number;
+    memories: Memory[];
+    filters: Record<string, any>;
+}
+interface NovyxConfig {
+    apiKey: string;
+    apiUrl?: string;
+    timeout?: number;
+    agentId?: string;
+}
+interface Edge {
+    edge_id: string;
+    source_id: string;
+    target_id: string;
+    relation: string;
+    weight: number;
+    metadata: Record<string, any>;
+    created_at: string;
+}
+interface LinksResult {
+    memory_id: string;
+    edges: Edge[];
+    total: number;
+}
+
+declare class NovyxSession {
+    private client;
+    private sessionTag;
+    constructor(client: Novyx, sessionId: string);
+    remember(observation: string, opts?: {
+        tags?: string[];
+        context?: string;
+        importance?: number;
+        agent_id?: string;
+        space_id?: string;
+        metadata?: Record<string, any>;
+        ttl_seconds?: number;
+    }): Promise<Record<string, any>>;
+    recall(query: string, opts?: {
+        limit?: number;
+        tags?: string[];
+        min_score?: number;
+        scope?: string;
+        agents?: string[];
+        include_shared?: boolean;
+        space_id?: string;
+    }): Promise<SearchResult>;
+    memories(opts?: {
+        limit?: number;
+        offset?: number;
+        tags?: string[];
+        min_importance?: number;
+        include_shared?: boolean;
+        agent_id?: string;
+        space_id?: string;
+    }): Promise<Memory[]>;
+    list(opts?: {
+        limit?: number;
+        offset?: number;
+        tags?: string[];
+        min_importance?: number;
+        include_shared?: boolean;
+        agent_id?: string;
+        space_id?: string;
+    }): Promise<ListResult>;
+}
+
+declare class Novyx {
+    private apiKey;
+    private apiUrl;
+    private timeout;
+    private agentId?;
+    constructor(config: NovyxConfig);
+    private _validateKey;
+    private _request;
+    remember(observation: string, opts?: {
+        tags?: string[];
+        context?: string;
+        importance?: number;
+        agent_id?: string;
+        space_id?: string;
+        metadata?: Record<string, any>;
+        ttl_seconds?: number;
+    }): Promise<Record<string, any>>;
+    recall(query: string, opts?: {
+        limit?: number;
+        tags?: string[];
+        min_score?: number;
+        scope?: string;
+        agents?: string[];
+        include_shared?: boolean;
+        space_id?: string;
+    }): Promise<SearchResult>;
+    memories(opts?: {
+        limit?: number;
+        offset?: number;
+        tags?: string[];
+        min_importance?: number;
+        include_shared?: boolean;
+        agent_id?: string;
+        space_id?: string;
+    }): Promise<Memory[]>;
+    memory(memoryId: string): Promise<Memory>;
+    forget(memoryId: string): Promise<boolean>;
+    delete(memoryId: string): Promise<boolean>;
+    list(opts?: {
+        limit?: number;
+        offset?: number;
+        tags?: string[];
+        min_importance?: number;
+        include_shared?: boolean;
+        agent_id?: string;
+        space_id?: string;
+    }): Promise<ListResult>;
+    stats(): Promise<Record<string, any>>;
+    shareContext(tag: string, toEmail: string, permission?: string): Promise<Record<string, any>>;
+    acceptSharedContext(token: string): Promise<Record<string, any>>;
+    sharedContexts(): Promise<Record<string, any>>;
+    revokeSharedContext(token: string): Promise<Record<string, any>>;
+    graph(opts?: {
+        include_shared?: boolean;
+        agents?: string[];
+    }): Promise<Record<string, any>>;
+    rollback(target: string, dryRun?: boolean, preserveEvidence?: boolean): Promise<Record<string, any>>;
+    rollbackPreview(target: string): Promise<Record<string, any>>;
+    rollbackHistory(limit?: number): Promise<Record<string, any>[]>;
+    audit(opts?: {
+        limit?: number;
+        since?: string;
+        until?: string;
+        operation?: string;
+        artifact_id?: string;
+    }): Promise<Record<string, any>[]>;
+    auditExport(format?: string): Promise<Response>;
+    auditVerify(): Promise<Record<string, any>>;
+    traceCreate(agentId: string, sessionId?: string, metadata?: Record<string, any>): Promise<Record<string, any>>;
+    traceStep(traceId: string, stepType: string, name: string, content?: string, attributes?: Record<string, any>): Promise<Record<string, any>>;
+    traceComplete(traceId: string): Promise<Record<string, any>>;
+    traceVerify(traceId: string): Promise<Record<string, any>>;
+    usage(): Promise<Record<string, any>>;
+    plans(): Promise<Record<string, any>[]>;
+    health(): Promise<Record<string, any>>;
+    session(sessionId: string): NovyxSession;
+    link(sourceId: string, targetId: string, opts?: {
+        relation?: string;
+        weight?: number;
+        metadata?: Record<string, any>;
+    }): Promise<Record<string, any>>;
+    unlink(sourceId: string, targetId: string, relation?: string): Promise<Record<string, any>>;
+    links(memoryId: string, relation?: string): Promise<LinksResult>;
+}
+
+declare class NovyxError extends Error {
+    constructor(message: string);
+}
+declare class NovyxAuthError extends NovyxError {
+    constructor(message?: string);
+}
+declare class NovyxForbiddenError extends NovyxError {
+    data: Record<string, any>;
+    feature?: string;
+    requiredPlan?: string;
+    upgradeUrl?: string;
+    constructor(message?: string, data?: Record<string, any>);
+}
+declare class NovyxRateLimitError extends NovyxError {
+    data: Record<string, any>;
+    limitType?: string;
+    current?: number;
+    limit?: number;
+    retryAfter?: number;
+    constructor(message?: string, data?: Record<string, any>);
+}
+declare class NovyxNotFoundError extends NovyxError {
+    constructor(message?: string);
+}
+declare class NovyxSecurityError extends NovyxError {
+    constructor(message?: string);
+}
+
+export { type Edge, type LinksResult, type ListResult, type Memory, Novyx, NovyxAuthError, type NovyxConfig, NovyxError, NovyxForbiddenError, NovyxNotFoundError, NovyxRateLimitError, NovyxSecurityError, NovyxSession, type SearchResult };

package/dist/index.js

@@ -0,0 +1,445 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Novyx: () => Novyx,
+  NovyxAuthError: () => NovyxAuthError,
+  NovyxError: () => NovyxError,
+  NovyxForbiddenError: () => NovyxForbiddenError,
+  NovyxNotFoundError: () => NovyxNotFoundError,
+  NovyxRateLimitError: () => NovyxRateLimitError,
+  NovyxSecurityError: () => NovyxSecurityError,
+  NovyxSession: () => NovyxSession
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var NovyxError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NovyxError";
+  }
+};
+var NovyxAuthError = class extends NovyxError {
+  constructor(message = "Invalid API key or unauthorized") {
+    super(message);
+    this.name = "NovyxAuthError";
+  }
+};
+var NovyxForbiddenError = class extends NovyxError {
+  constructor(message = "Forbidden", data = {}) {
+    super(message);
+    this.name = "NovyxForbiddenError";
+    this.data = data;
+    this.feature = data.feature;
+    this.requiredPlan = data.required_plan ?? "pro";
+    this.upgradeUrl = data.upgrade_url ?? "https://novyxlabs.com/pricing";
+  }
+};
+var NovyxRateLimitError = class extends NovyxError {
+  constructor(message = "Rate limit exceeded", data = {}) {
+    super(message);
+    this.name = "NovyxRateLimitError";
+    this.data = data;
+    this.limitType = data.limit;
+    this.current = data.current;
+    this.limit = data.max_allowed ?? data.max ?? data.limit;
+    this.retryAfter = data.retry_after;
+  }
+};
+var NovyxNotFoundError = class extends NovyxError {
+  constructor(message = "Not found") {
+    super(message);
+    this.name = "NovyxNotFoundError";
+  }
+};
+var NovyxSecurityError = class extends NovyxError {
+  constructor(message = "Security policy violation") {
+    super(message);
+    this.name = "NovyxSecurityError";
+  }
+};
+
+// src/session.ts
+var NovyxSession = class {
+  constructor(client, sessionId) {
+    this.client = client;
+    this.sessionTag = `session:${sessionId}`;
+  }
+  async remember(observation, opts) {
+    const tags = [...opts?.tags ?? [], this.sessionTag];
+    return this.client.remember(observation, { ...opts, tags });
+  }
+  async recall(query, opts) {
+    const tags = [...opts?.tags ?? [], this.sessionTag];
+    return this.client.recall(query, { ...opts, tags });
+  }
+  async memories(opts) {
+    const tags = [...opts?.tags ?? [], this.sessionTag];
+    return this.client.memories({ ...opts, tags });
+  }
+  async list(opts) {
+    const tags = [...opts?.tags ?? [], this.sessionTag];
+    return this.client.list({ ...opts, tags });
+  }
+};
+
+// src/client.ts
+var Novyx = class {
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.apiUrl = (config.apiUrl ?? "https://novyx-ram-api.fly.dev").replace(/\/+$/, "");
+    this.timeout = config.timeout ?? 30;
+    this.agentId = config.agentId;
+    this._validateKey();
+  }
+  _validateKey() {
+    if (!this.apiKey || !this.apiKey.startsWith("nram_")) {
+      throw new NovyxAuthError("Invalid API key format. Expected: nram_<tenant>_<signature>");
+    }
+  }
+  async _request(method, endpoint, opts) {
+    const url = new URL(`${this.apiUrl}${endpoint}`);
+    if (opts?.params) {
+      for (const [key, value] of Object.entries(opts.params)) {
+        if (value !== void 0 && value !== null) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout * 1e3);
+    try {
+      const fetchOpts = {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json"
+        },
+        signal: controller.signal
+      };
+      if (opts?.body && (method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE")) {
+        fetchOpts.body = JSON.stringify(opts.body);
+      }
+      const response = await fetch(url.toString(), fetchOpts);
+      if (response.status === 401) {
+        throw new NovyxAuthError("Invalid API key or unauthorized");
+      }
+      if (response.status === 403) {
+        let data = {};
+        try {
+          data = await response.json();
+        } catch {
+        }
+        throw new NovyxForbiddenError(data.error ?? "Forbidden", data);
+      }
+      if (response.status === 404) {
+        let data = {};
+        try {
+          data = await response.json();
+        } catch {
+        }
+        throw new NovyxNotFoundError(data.error ?? "Not found");
+      }
+      if (response.status === 429) {
+        let data = {};
+        try {
+          data = await response.json();
+        } catch {
+        }
+        throw new NovyxRateLimitError(data.error ?? "Rate limit exceeded", data);
+      }
+      if (opts?.rawResponse) {
+        return response;
+      }
+      if (response.status === 204 || response.headers.get("content-length") === "0") {
+        return {};
+      }
+      const text = await response.text();
+      if (!text) {
+        return {};
+      }
+      let json;
+      try {
+        json = JSON.parse(text);
+      } catch {
+        if (response.status >= 400) {
+          throw new NovyxError(`HTTP ${response.status}: ${text.slice(0, 200)}`);
+        }
+        throw new NovyxError(`Invalid JSON response: ${text.slice(0, 200)}`);
+      }
+      if (response.status >= 400) {
+        throw new NovyxError(`HTTP ${response.status}: ${json.error ?? JSON.stringify(json).slice(0, 200)}`);
+      }
+      return json;
+    } catch (err) {
+      if (err instanceof NovyxError) throw err;
+      if (err.name === "AbortError") {
+        throw new NovyxError(`Request timed out after ${this.timeout}s`);
+      }
+      throw new NovyxError(`Request failed: ${err.message}`);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  // ========================================================================
+  // Memory Methods
+  // ========================================================================
+  async remember(observation, opts) {
+    const resolvedAgentId = opts?.agent_id ?? this.agentId;
+    const body = {
+      observation,
+      tags: opts?.tags ?? [],
+      importance: opts?.importance ?? 5
+    };
+    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;
+    if (opts?.context) {
+      body.context = opts.context;
+    } else if (opts?.metadata) {
+      body.context = JSON.stringify(opts.metadata);
+    }
+    return this._request("POST", "/v1/memories", { body });
+  }
+  async recall(query, opts) {
+    const params = {
+      q: query,
+      limit: opts?.limit ?? 5,
+      min_score: opts?.min_score ?? 0
+    };
+    if (opts?.tags) params.tags = opts.tags.join(",");
+    if (opts?.agents) params.agents = opts.agents.join(",");
+    if (opts?.space_id) params.space_id = opts.space_id;
+    const result = await this._request("GET", "/v1/memories/search", { params });
+    const raw = Array.isArray(result) ? result : result.memories ?? [];
+    return {
+      query,
+      total_results: raw.length,
+      memories: raw
+    };
+  }
+  async memories(opts) {
+    const params = {
+      limit: opts?.limit ?? 100,
+      offset: opts?.offset ?? 0
+    };
+    if (opts?.tags) params.tags = opts.tags.join(",");
+    if (opts?.min_importance !== void 0) params.min_importance = opts.min_importance;
+    if (opts?.include_shared) params.include_shared = "true";
+    if (opts?.agent_id) params.agent_id = opts.agent_id;
+    if (opts?.space_id) params.space_id = opts.space_id;
+    const result = await this._request("GET", "/v1/memories", { params });
+    return typeof result === "object" && !Array.isArray(result) ? result.memories ?? [] : result;
+  }
+  async memory(memoryId) {
+    return this._request("GET", `/v1/memories/${memoryId}`);
+  }
+  async forget(memoryId) {
+    const result = await this._request("DELETE", `/v1/memories/${memoryId}`);
+    return result?.success ?? true;
+  }
+  async delete(memoryId) {
+    return this.forget(memoryId);
+  }
+  async list(opts) {
+    const params = {
+      limit: opts?.limit ?? 100,
+      offset: opts?.offset ?? 0
+    };
+    if (opts?.tags) params.tags = opts.tags.join(",");
+    if (opts?.min_importance !== void 0) params.min_importance = opts.min_importance;
+    if (opts?.include_shared) params.include_shared = "true";
+    if (opts?.agent_id) params.agent_id = opts.agent_id;
+    if (opts?.space_id) params.space_id = opts.space_id;
+    const result = await this._request("GET", "/v1/memories", { params });
+    const rawMemories = typeof result === "object" && !Array.isArray(result) ? result.memories ?? [] : result;
+    return {
+      total_count: typeof result === "object" && !Array.isArray(result) ? result.total_count ?? rawMemories.length : rawMemories.length,
+      memories: rawMemories,
+      filters: typeof result === "object" && !Array.isArray(result) ? result.filters ?? {} : {}
+    };
+  }
+  async stats() {
+    return this._request("GET", "/v1/memories/stats");
+  }
+  // ========================================================================
+  // Context Space & Sharing
+  // ========================================================================
+  async shareContext(tag, toEmail, permission = "read") {
+    return this._request("POST", "/v1/spaces/share", {
+      body: { tag, email: toEmail, permission }
+    });
+  }
+  async acceptSharedContext(token) {
+    return this._request("POST", "/v1/spaces/join", {
+      body: { token }
+    });
+  }
+  async sharedContexts() {
+    return this._request("GET", "/v1/spaces/shared");
+  }
+  async revokeSharedContext(token) {
+    return this._request("DELETE", `/v1/spaces/share/${token}`);
+  }
+  async graph(opts) {
+    const params = {};
+    if (opts?.include_shared) params.include_shared = "true";
+    if (opts?.agents) params.agents = opts.agents.join(",");
+    return this._request("GET", "/v1/memories/graph", { params });
+  }
+  // ========================================================================
+  // Rollback
+  // ========================================================================
+  async rollback(target, dryRun = false, preserveEvidence = true) {
+    return this._request("POST", "/v1/rollback", {
+      body: { target, dry_run: dryRun, preserve_evidence: preserveEvidence }
+    });
+  }
+  async rollbackPreview(target) {
+    return this._request("GET", "/v1/rollback/preview", {
+      params: { target }
+    });
+  }
+  async rollbackHistory(limit = 50) {
+    const result = await this._request("GET", "/v1/rollback/history", {
+      params: { limit }
+    });
+    return Array.isArray(result) ? result : [];
+  }
+  // ========================================================================
+  // Audit
+  // ========================================================================
+  async audit(opts) {
+    const params = { limit: opts?.limit ?? 50 };
+    if (opts?.since) params.start_time = opts.since;
+    if (opts?.until) params.end_time = opts.until;
+    if (opts?.operation) params.operation = opts.operation;
+    if (opts?.artifact_id) params.artifact_id = opts.artifact_id;
+    const result = await this._request("GET", "/v1/audit", { params });
+    return typeof result === "object" && !Array.isArray(result) ? result.entries ?? [] : result;
+  }
+  async auditExport(format = "csv") {
+    return this._request("GET", "/v1/audit/export", {
+      params: { format },
+      rawResponse: true
+    });
+  }
+  async auditVerify() {
+    return this._request("GET", "/v1/audit/verify");
+  }
+  // ========================================================================
+  // Traces
+  // ========================================================================
+  async traceCreate(agentId, sessionId, metadata) {
+    return this._request("POST", "/v1/traces", {
+      body: {
+        agent_id: agentId,
+        session_id: sessionId,
+        metadata: metadata ?? {}
+      }
+    });
+  }
+  async traceStep(traceId, stepType, name, content, attributes) {
+    return this._request("POST", `/v1/traces/${traceId}/steps`, {
+      body: {
+        step_type: stepType,
+        name,
+        content,
+        attributes: attributes ?? {}
+      }
+    });
+  }
+  async traceComplete(traceId) {
+    return this._request("POST", `/v1/traces/${traceId}/complete`);
+  }
+  async traceVerify(traceId) {
+    return this._request("GET", `/v1/traces/${traceId}/verify`);
+  }
+  // ========================================================================
+  // Usage & Plans
+  // ========================================================================
+  async usage() {
+    return this._request("GET", "/v1/usage");
+  }
+  async plans() {
+    return this._request("GET", "/v1/plans");
+  }
+  async health() {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout * 1e3);
+      try {
+        const response = await fetch(`${this.apiUrl}/health`, {
+          signal: controller.signal
+        });
+        return await response.json();
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    } catch (err) {
+      return { status: "error", error: err.message };
+    }
+  }
+  // ========================================================================
+  // Sessions
+  // ========================================================================
+  session(sessionId) {
+    return new NovyxSession(this, sessionId);
+  }
+  // ========================================================================
+  // Links / Edges
+  // ========================================================================
+  async link(sourceId, targetId, opts) {
+    const body = {
+      source_id: sourceId,
+      target_id: targetId
+    };
+    if (opts?.relation) body.relation = opts.relation;
+    if (opts?.weight !== void 0) body.weight = opts.weight;
+    if (opts?.metadata) body.metadata = opts.metadata;
+    return this._request("POST", "/v1/memories/link", { body });
+  }
+  async unlink(sourceId, targetId, relation) {
+    const body = {
+      source_id: sourceId,
+      target_id: targetId
+    };
+    if (relation) body.relation = relation;
+    return this._request("DELETE", "/v1/memories/link", { body });
+  }
+  async links(memoryId, relation) {
+    const params = {};
+    if (relation) params.relation = relation;
+    return this._request("GET", `/v1/memories/${memoryId}/links`, { params });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Novyx,
+  NovyxAuthError,
+  NovyxError,
+  NovyxForbiddenError,
+  NovyxNotFoundError,
+  NovyxRateLimitError,
+  NovyxSecurityError,
+  NovyxSession
+});

package/dist/index.mjs

@@ -0,0 +1,411 @@
+// src/errors.ts
+var NovyxError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NovyxError";
+  }
+};
+var NovyxAuthError = class extends NovyxError {
+  constructor(message = "Invalid API key or unauthorized") {
+    super(message);
+    this.name = "NovyxAuthError";
+  }
+};
+var NovyxForbiddenError = class extends NovyxError {
+  constructor(message = "Forbidden", data = {}) {
+    super(message);
+    this.name = "NovyxForbiddenError";
+    this.data = data;
+    this.feature = data.feature;
+    this.requiredPlan = data.required_plan ?? "pro";
+    this.upgradeUrl = data.upgrade_url ?? "https://novyxlabs.com/pricing";
+  }
+};
+var NovyxRateLimitError = class extends NovyxError {
+  constructor(message = "Rate limit exceeded", data = {}) {
+    super(message);
+    this.name = "NovyxRateLimitError";
+    this.data = data;
+    this.limitType = data.limit;
+    this.current = data.current;
+    this.limit = data.max_allowed ?? data.max ?? data.limit;
+    this.retryAfter = data.retry_after;
+  }
+};
+var NovyxNotFoundError = class extends NovyxError {
+  constructor(message = "Not found") {
+    super(message);
+    this.name = "NovyxNotFoundError";
+  }
+};
+var NovyxSecurityError = class extends NovyxError {
+  constructor(message = "Security policy violation") {
+    super(message);
+    this.name = "NovyxSecurityError";
+  }
+};
+
+// src/session.ts
+var NovyxSession = class {
+  constructor(client, sessionId) {
+    this.client = client;
+    this.sessionTag = `session:${sessionId}`;
+  }
+  async remember(observation, opts) {
+    const tags = [...opts?.tags ?? [], this.sessionTag];
+    return this.client.remember(observation, { ...opts, tags });
+  }
+  async recall(query, opts) {
+    const tags = [...opts?.tags ?? [], this.sessionTag];
+    return this.client.recall(query, { ...opts, tags });
+  }
+  async memories(opts) {
+    const tags = [...opts?.tags ?? [], this.sessionTag];
+    return this.client.memories({ ...opts, tags });
+  }
+  async list(opts) {
+    const tags = [...opts?.tags ?? [], this.sessionTag];
+    return this.client.list({ ...opts, tags });
+  }
+};
+
+// src/client.ts
+var Novyx = class {
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.apiUrl = (config.apiUrl ?? "https://novyx-ram-api.fly.dev").replace(/\/+$/, "");
+    this.timeout = config.timeout ?? 30;
+    this.agentId = config.agentId;
+    this._validateKey();
+  }
+  _validateKey() {
+    if (!this.apiKey || !this.apiKey.startsWith("nram_")) {
+      throw new NovyxAuthError("Invalid API key format. Expected: nram_<tenant>_<signature>");
+    }
+  }
+  async _request(method, endpoint, opts) {
+    const url = new URL(`${this.apiUrl}${endpoint}`);
+    if (opts?.params) {
+      for (const [key, value] of Object.entries(opts.params)) {
+        if (value !== void 0 && value !== null) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout * 1e3);
+    try {
+      const fetchOpts = {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json"
+        },
+        signal: controller.signal
+      };
+      if (opts?.body && (method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE")) {
+        fetchOpts.body = JSON.stringify(opts.body);
+      }
+      const response = await fetch(url.toString(), fetchOpts);
+      if (response.status === 401) {
+        throw new NovyxAuthError("Invalid API key or unauthorized");
+      }
+      if (response.status === 403) {
+        let data = {};
+        try {
+          data = await response.json();
+        } catch {
+        }
+        throw new NovyxForbiddenError(data.error ?? "Forbidden", data);
+      }
+      if (response.status === 404) {
+        let data = {};
+        try {
+          data = await response.json();
+        } catch {
+        }
+        throw new NovyxNotFoundError(data.error ?? "Not found");
+      }
+      if (response.status === 429) {
+        let data = {};
+        try {
+          data = await response.json();
+        } catch {
+        }
+        throw new NovyxRateLimitError(data.error ?? "Rate limit exceeded", data);
+      }
+      if (opts?.rawResponse) {
+        return response;
+      }
+      if (response.status === 204 || response.headers.get("content-length") === "0") {
+        return {};
+      }
+      const text = await response.text();
+      if (!text) {
+        return {};
+      }
+      let json;
+      try {
+        json = JSON.parse(text);
+      } catch {
+        if (response.status >= 400) {
+          throw new NovyxError(`HTTP ${response.status}: ${text.slice(0, 200)}`);
+        }
+        throw new NovyxError(`Invalid JSON response: ${text.slice(0, 200)}`);
+      }
+      if (response.status >= 400) {
+        throw new NovyxError(`HTTP ${response.status}: ${json.error ?? JSON.stringify(json).slice(0, 200)}`);
+      }
+      return json;
+    } catch (err) {
+      if (err instanceof NovyxError) throw err;
+      if (err.name === "AbortError") {
+        throw new NovyxError(`Request timed out after ${this.timeout}s`);
+      }
+      throw new NovyxError(`Request failed: ${err.message}`);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  // ========================================================================
+  // Memory Methods
+  // ========================================================================
+  async remember(observation, opts) {
+    const resolvedAgentId = opts?.agent_id ?? this.agentId;
+    const body = {
+      observation,
+      tags: opts?.tags ?? [],
+      importance: opts?.importance ?? 5
+    };
+    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;
+    if (opts?.context) {
+      body.context = opts.context;
+    } else if (opts?.metadata) {
+      body.context = JSON.stringify(opts.metadata);
+    }
+    return this._request("POST", "/v1/memories", { body });
+  }
+  async recall(query, opts) {
+    const params = {
+      q: query,
+      limit: opts?.limit ?? 5,
+      min_score: opts?.min_score ?? 0
+    };
+    if (opts?.tags) params.tags = opts.tags.join(",");
+    if (opts?.agents) params.agents = opts.agents.join(",");
+    if (opts?.space_id) params.space_id = opts.space_id;
+    const result = await this._request("GET", "/v1/memories/search", { params });
+    const raw = Array.isArray(result) ? result : result.memories ?? [];
+    return {
+      query,
+      total_results: raw.length,
+      memories: raw
+    };
+  }
+  async memories(opts) {
+    const params = {
+      limit: opts?.limit ?? 100,
+      offset: opts?.offset ?? 0
+    };
+    if (opts?.tags) params.tags = opts.tags.join(",");
+    if (opts?.min_importance !== void 0) params.min_importance = opts.min_importance;
+    if (opts?.include_shared) params.include_shared = "true";
+    if (opts?.agent_id) params.agent_id = opts.agent_id;
+    if (opts?.space_id) params.space_id = opts.space_id;
+    const result = await this._request("GET", "/v1/memories", { params });
+    return typeof result === "object" && !Array.isArray(result) ? result.memories ?? [] : result;
+  }
+  async memory(memoryId) {
+    return this._request("GET", `/v1/memories/${memoryId}`);
+  }
+  async forget(memoryId) {
+    const result = await this._request("DELETE", `/v1/memories/${memoryId}`);
+    return result?.success ?? true;
+  }
+  async delete(memoryId) {
+    return this.forget(memoryId);
+  }
+  async list(opts) {
+    const params = {
+      limit: opts?.limit ?? 100,
+      offset: opts?.offset ?? 0
+    };
+    if (opts?.tags) params.tags = opts.tags.join(",");
+    if (opts?.min_importance !== void 0) params.min_importance = opts.min_importance;
+    if (opts?.include_shared) params.include_shared = "true";
+    if (opts?.agent_id) params.agent_id = opts.agent_id;
+    if (opts?.space_id) params.space_id = opts.space_id;
+    const result = await this._request("GET", "/v1/memories", { params });
+    const rawMemories = typeof result === "object" && !Array.isArray(result) ? result.memories ?? [] : result;
+    return {
+      total_count: typeof result === "object" && !Array.isArray(result) ? result.total_count ?? rawMemories.length : rawMemories.length,
+      memories: rawMemories,
+      filters: typeof result === "object" && !Array.isArray(result) ? result.filters ?? {} : {}
+    };
+  }
+  async stats() {
+    return this._request("GET", "/v1/memories/stats");
+  }
+  // ========================================================================
+  // Context Space & Sharing
+  // ========================================================================
+  async shareContext(tag, toEmail, permission = "read") {
+    return this._request("POST", "/v1/spaces/share", {
+      body: { tag, email: toEmail, permission }
+    });
+  }
+  async acceptSharedContext(token) {
+    return this._request("POST", "/v1/spaces/join", {
+      body: { token }
+    });
+  }
+  async sharedContexts() {
+    return this._request("GET", "/v1/spaces/shared");
+  }
+  async revokeSharedContext(token) {
+    return this._request("DELETE", `/v1/spaces/share/${token}`);
+  }
+  async graph(opts) {
+    const params = {};
+    if (opts?.include_shared) params.include_shared = "true";
+    if (opts?.agents) params.agents = opts.agents.join(",");
+    return this._request("GET", "/v1/memories/graph", { params });
+  }
+  // ========================================================================
+  // Rollback
+  // ========================================================================
+  async rollback(target, dryRun = false, preserveEvidence = true) {
+    return this._request("POST", "/v1/rollback", {
+      body: { target, dry_run: dryRun, preserve_evidence: preserveEvidence }
+    });
+  }
+  async rollbackPreview(target) {
+    return this._request("GET", "/v1/rollback/preview", {
+      params: { target }
+    });
+  }
+  async rollbackHistory(limit = 50) {
+    const result = await this._request("GET", "/v1/rollback/history", {
+      params: { limit }
+    });
+    return Array.isArray(result) ? result : [];
+  }
+  // ========================================================================
+  // Audit
+  // ========================================================================
+  async audit(opts) {
+    const params = { limit: opts?.limit ?? 50 };
+    if (opts?.since) params.start_time = opts.since;
+    if (opts?.until) params.end_time = opts.until;
+    if (opts?.operation) params.operation = opts.operation;
+    if (opts?.artifact_id) params.artifact_id = opts.artifact_id;
+    const result = await this._request("GET", "/v1/audit", { params });
+    return typeof result === "object" && !Array.isArray(result) ? result.entries ?? [] : result;
+  }
+  async auditExport(format = "csv") {
+    return this._request("GET", "/v1/audit/export", {
+      params: { format },
+      rawResponse: true
+    });
+  }
+  async auditVerify() {
+    return this._request("GET", "/v1/audit/verify");
+  }
+  // ========================================================================
+  // Traces
+  // ========================================================================
+  async traceCreate(agentId, sessionId, metadata) {
+    return this._request("POST", "/v1/traces", {
+      body: {
+        agent_id: agentId,
+        session_id: sessionId,
+        metadata: metadata ?? {}
+      }
+    });
+  }
+  async traceStep(traceId, stepType, name, content, attributes) {
+    return this._request("POST", `/v1/traces/${traceId}/steps`, {
+      body: {
+        step_type: stepType,
+        name,
+        content,
+        attributes: attributes ?? {}
+      }
+    });
+  }
+  async traceComplete(traceId) {
+    return this._request("POST", `/v1/traces/${traceId}/complete`);
+  }
+  async traceVerify(traceId) {
+    return this._request("GET", `/v1/traces/${traceId}/verify`);
+  }
+  // ========================================================================
+  // Usage & Plans
+  // ========================================================================
+  async usage() {
+    return this._request("GET", "/v1/usage");
+  }
+  async plans() {
+    return this._request("GET", "/v1/plans");
+  }
+  async health() {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout * 1e3);
+      try {
+        const response = await fetch(`${this.apiUrl}/health`, {
+          signal: controller.signal
+        });
+        return await response.json();
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    } catch (err) {
+      return { status: "error", error: err.message };
+    }
+  }
+  // ========================================================================
+  // Sessions
+  // ========================================================================
+  session(sessionId) {
+    return new NovyxSession(this, sessionId);
+  }
+  // ========================================================================
+  // Links / Edges
+  // ========================================================================
+  async link(sourceId, targetId, opts) {
+    const body = {
+      source_id: sourceId,
+      target_id: targetId
+    };
+    if (opts?.relation) body.relation = opts.relation;
+    if (opts?.weight !== void 0) body.weight = opts.weight;
+    if (opts?.metadata) body.metadata = opts.metadata;
+    return this._request("POST", "/v1/memories/link", { body });
+  }
+  async unlink(sourceId, targetId, relation) {
+    const body = {
+      source_id: sourceId,
+      target_id: targetId
+    };
+    if (relation) body.relation = relation;
+    return this._request("DELETE", "/v1/memories/link", { body });
+  }
+  async links(memoryId, relation) {
+    const params = {};
+    if (relation) params.relation = relation;
+    return this._request("GET", `/v1/memories/${memoryId}/links`, { params });
+  }
+};
+export {
+  Novyx,
+  NovyxAuthError,
+  NovyxError,
+  NovyxForbiddenError,
+  NovyxNotFoundError,
+  NovyxRateLimitError,
+  NovyxSecurityError,
+  NovyxSession
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "novyx",
+  "version": "2.2.0",
+  "description": "Novyx SDK - Persistent memory, rollback, and audit trail for AI agents",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "lint": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "license": "MIT",
+  "author": "Novyx Labs"
+}