comemo 1.0.0

package/README.md

@@ -0,0 +1,148 @@
+# CoMemo SDK
+
+Node.js SDK for CoMemo — a multi-module hybrid memory system powered by Pinecone and Neo4j.
+
+## Installation
+
+```bash
+npm install comemo
+```
+
+## Quick Start
+
+Each client requires your own infrastructure credentials. All operations use your own Pinecone index, Neo4j database, and LLM API key.
+
+```ts
+import { MemoryClient } from "comemo";
+
+const client = new MemoryClient({
+  llmApiKey: "sk-your-openai-key",
+  model: "gpt-4o-mini",
+  pineconeApiKey: "pc-...",
+  pineconeIndex: "my-memory-index",
+  neo4jUri: "neo4j+s://xxx.databases.neo4j.io",
+  neo4jUsername: "neo4j",
+  neo4jPassword: "...",
+});
+```
+
+Optional fields:
+
+```ts
+const client = new MemoryClient({
+  ...,
+  pineconeNamespace: "tenant-a",   // Multi-tenant within one Pinecone index
+  neo4jDatabase: "mydb",           // Neo4j database name (defaults to "neo4j")
+  baseUrl: "https://xvert.io",    // API base URL
+  timeout: 30000,                  // Request timeout in ms
+});
+```
+
+### Core Memory
+
+```ts
+// Add a memory
+const result = await client.addMemory("john", "chat_01", "I work at Google as a software engineer");
+console.log(result.status);     // "success"
+console.log(result.action);     // "NEW"
+console.log(result.memory_id);  // "mem_abc123"
+
+// Delete all user memories
+await client.deleteUserMemories("john");
+
+// Delete session memories
+await client.deleteSessionMemories("john", "chat_01");
+
+// Delete a single memory
+await client.deleteMemory("mem_abc123");
+```
+
+### Retrieval
+
+```ts
+// Simple retrieve
+const simple = await client.retrieve("john", "chat_01", "Where does John work?", 5);
+for (const m of simple.memories) {
+  console.log(`${m.fact} (score: ${m.score})`);
+}
+
+// Advanced retrieve with full scoring breakdown
+const result = await client.retrieveAdvanced("john", "chat_01", "career and hobbies", {
+  topK: 10,
+  expandContext: true,
+  expandGraph: true,
+  minScore: 0.3,
+  reinforce: true,
+});
+for (const m of result.memories) {
+  console.log(`${m.fact} | semantic=${m.semantic_similarity} graph=${m.graph_relevance}`);
+}
+
+// List memories across all sessions
+const list = await client.listMemories("john", "work", 10);
+
+// Retrieve with LLM summary
+const summary = await client.retrieveSummary("john", "chat_01", "Tell me about John's career");
+console.log(summary.summary);
+```
+
+### Maintenance
+
+```ts
+// Run maintenance tasks (decay, forgetting, summarization)
+const result = await client.runMaintenance("john");
+
+// Selective tasks
+const result = await client.runMaintenance("john", {
+  decay: true,
+  forgetting: true,
+  summarization: false,
+});
+
+// Dry run
+const result = await client.runMaintenance("john", undefined, true);
+```
+
+### System
+
+```ts
+const health = await client.health();
+console.log(health.status);        // "healthy"
+console.log(health.version);       // "6.0.0"
+console.log(health.architecture);  // "Multi-Module Hybrid Memory (Multi-Tenant)"
+```
+
+## Error Handling
+
+```ts
+import { MemoryClient, ValidationError, NotFoundError } from "comemo";
+
+try {
+  await client.retrieve("john", "chat_01", "");
+} catch (e) {
+  if (e instanceof ValidationError) {
+    console.log(`Bad request: ${e.message}`);
+  } else if (e instanceof NotFoundError) {
+    console.log(`Not found: ${e.message}`);
+  }
+}
+```
+
+## All Methods
+
+| Method | Description |
+|---|---|
+| `addMemory(userId, sessionId, text)` | Extract facts and store as memories |
+| `deleteMemory(memoryId)` | Delete a single memory |
+| `deleteUserMemories(userId)` | Delete all memories for a user |
+| `deleteSessionMemories(userId, sessionId)` | Delete all memories for a session |
+| `retrieve(userId, sessionId, query, topK?)` | Simple retrieval |
+| `retrieveAdvanced(userId, sessionId, query, options?)` | Advanced retrieval with scoring |
+| `listMemories(userId, query, topK?)` | List memories across sessions |
+| `retrieveSummary(userId, sessionId, query, topK?)` | Retrieve with LLM summary |
+| `runMaintenance(userId, tasks?, dryRun?)` | Run tenant-scoped maintenance |
+| `health()` | Health check |
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,121 @@
+import type { AddMemoryResult, DeleteResult, DetailedRetrieveResult, HealthResult, MaintenanceResult, MaintenanceTaskOptions, MemoryClientOptions, RetrieveAdvancedOptions, RetrieveResult, RetrieveSummaryResult } from "./types";
+/**
+ * Client for the CogMemo API.
+ *
+ * Each client instance represents a single tenant with its own infrastructure
+ * credentials. All operations are scoped to the tenant's own Pinecone index,
+ * Neo4j database, and LLM API key.
+ *
+ * @example
+ * ```ts
+ * const client = new MemoryClient({
+ *   llmApiKey: "sk-your-openai-key",
+ *   model: "gpt-4o-mini",
+ *   pineconeApiKey: "pc-...",
+ *   pineconeIndex: "user-memory-index",
+ *   neo4jUri: "neo4j+s://xxx.databases.neo4j.io",
+ *   neo4jUsername: "neo4j",
+ *   neo4jPassword: "...",
+ * });
+ *
+ * await client.addMemory("john", "chat_01", "I work at Google");
+ * const result = await client.retrieve("john", "chat_01", "Where does John work?");
+ * ```
+ */
+export declare class MemoryClient {
+    private baseUrl;
+    private timeout;
+    private config;
+    /**
+     * Create a new MemoryClient.
+     *
+     * @param options - Client configuration options including tenant credentials.
+     */
+    constructor(options: MemoryClientOptions);
+    private request;
+    /**
+     * Extract facts from text and store them as memories.
+     *
+     * @param userId - User ID for memory isolation.
+     * @param sessionId - Session ID for context grouping.
+     * @param text - Input text to extract facts from.
+     * @returns Result with status, action, memory_id, links_created, and score.
+     */
+    addMemory(userId: string, sessionId: string, text: string): Promise<AddMemoryResult>;
+    /**
+     * Delete a single memory by ID.
+     *
+     * @param memoryId - The memory identifier to delete.
+     * @returns Object with status, memory_id, and deleted flag.
+     */
+    deleteMemory(memoryId: string): Promise<Record<string, unknown>>;
+    /**
+     * Delete all memories for a user.
+     *
+     * @param userId - The user whose memories to delete.
+     * @returns DeleteResult with count of deleted memories.
+     */
+    deleteUserMemories(userId: string): Promise<DeleteResult>;
+    /**
+     * Delete all memories for a specific session.
+     *
+     * @param userId - The user ID.
+     * @param sessionId - The session whose memories to delete.
+     * @returns DeleteResult with count of deleted memories.
+     */
+    deleteSessionMemories(userId: string, sessionId: string): Promise<DeleteResult>;
+    /**
+     * Retrieve top memories matching a query (simple mode).
+     *
+     * @param userId - User ID for namespace isolation.
+     * @param sessionId - Current session ID.
+     * @param query - Search query text.
+     * @param topK - Maximum number of results (1-50). Defaults to 5.
+     * @returns RetrieveResult with query, expanded query, and list of memories.
+     */
+    retrieve(userId: string, sessionId: string, query: string, topK?: number): Promise<RetrieveResult>;
+    /**
+     * Retrieve memories with full scoring details and advanced options.
+     *
+     * @param userId - User ID for namespace isolation.
+     * @param sessionId - Current session ID.
+     * @param query - Search query text.
+     * @param options - Advanced retrieval options.
+     * @returns DetailedRetrieveResult with full scoring breakdown per memory.
+     */
+    retrieveAdvanced(userId: string, sessionId: string, query: string, options?: RetrieveAdvancedOptions): Promise<DetailedRetrieveResult>;
+    /**
+     * Retrieve memories and get an LLM-generated summary.
+     *
+     * @param userId - User ID for namespace isolation.
+     * @param sessionId - Current session ID.
+     * @param query - Search query text.
+     * @param topK - Number of memories to summarize (1-20). Defaults to 5.
+     * @returns RetrieveSummaryResult with summary text and supporting memories.
+     */
+    retrieveSummary(userId: string, sessionId: string, query: string, topK?: number): Promise<RetrieveSummaryResult>;
+    /**
+     * List user memories across all sessions.
+     *
+     * @param userId - User ID.
+     * @param query - Search query text.
+     * @param topK - Maximum number of results (1-50). Defaults to 10.
+     * @returns RetrieveResult with matching memories across all sessions.
+     */
+    listMemories(userId: string, query: string, topK?: number): Promise<RetrieveResult>;
+    /**
+     * Run tenant-scoped maintenance tasks for a user.
+     *
+     * @param userId - User ID to scope maintenance to (required).
+     * @param tasks - Which tasks to run. Defaults to decay + forgetting + summarization.
+     * @param dryRun - If true, only identify but don't modify memories.
+     * @returns MaintenanceResult with per-task results.
+     */
+    runMaintenance(userId: string, tasks?: MaintenanceTaskOptions, dryRun?: boolean): Promise<MaintenanceResult>;
+    /**
+     * Check API health and status.
+     *
+     * @returns HealthResult with status, version, and architecture.
+     */
+    health(): Promise<HealthResult>;
+}

package/dist/client.js

@@ -0,0 +1,329 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryClient = void 0;
+const errors_1 = require("./errors");
+/**
+ * Client for the CogMemo API.
+ *
+ * Each client instance represents a single tenant with its own infrastructure
+ * credentials. All operations are scoped to the tenant's own Pinecone index,
+ * Neo4j database, and LLM API key.
+ *
+ * @example
+ * ```ts
+ * const client = new MemoryClient({
+ *   llmApiKey: "sk-your-openai-key",
+ *   model: "gpt-4o-mini",
+ *   pineconeApiKey: "pc-...",
+ *   pineconeIndex: "user-memory-index",
+ *   neo4jUri: "neo4j+s://xxx.databases.neo4j.io",
+ *   neo4jUsername: "neo4j",
+ *   neo4jPassword: "...",
+ * });
+ *
+ * await client.addMemory("john", "chat_01", "I work at Google");
+ * const result = await client.retrieve("john", "chat_01", "Where does John work?");
+ * ```
+ */
+class MemoryClient {
+    baseUrl;
+    timeout;
+    config;
+    /**
+     * Create a new MemoryClient.
+     *
+     * @param options - Client configuration options including tenant credentials.
+     */
+    constructor(options) {
+        this.baseUrl = (options.baseUrl ?? "https://xvert.io").replace(/\/+$/, "");
+        this.timeout = options.timeout ?? 30000;
+        // Tenant config sent with every request
+        const cfg = {
+            llm_api_key: options.llmApiKey,
+            model: options.model ?? "gpt-4o-mini",
+            pinecone_api_key: options.pineconeApiKey,
+            pinecone_index: options.pineconeIndex,
+            neo4j_uri: options.neo4jUri,
+            neo4j_username: options.neo4jUsername,
+            neo4j_password: options.neo4jPassword,
+        };
+        if (options.pineconeNamespace)
+            cfg.pinecone_namespace = options.pineconeNamespace;
+        if (options.neo4jDatabase)
+            cfg.neo4j_database = options.neo4jDatabase;
+        this.config = cfg;
+    }
+    async request(method, path, options = {}) {
+        let url = `${this.baseUrl}${path}`;
+        if (options.params) {
+            const search = new URLSearchParams();
+            for (const [key, value] of Object.entries(options.params)) {
+                search.set(key, String(value));
+            }
+            url += `?${search.toString()}`;
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const fetchOptions = {
+                method,
+                headers: { "Content-Type": "application/json" },
+                signal: controller.signal,
+            };
+            if (options.body) {
+                fetchOptions.body = JSON.stringify(options.body);
+            }
+            const response = await fetch(url, fetchOptions);
+            if (!response.ok) {
+                let detail;
+                try {
+                    const body = (await response.json());
+                    detail = body.detail ?? response.statusText;
+                }
+                catch {
+                    detail = response.statusText;
+                }
+                if (response.status === 401 || response.status === 403) {
+                    throw new errors_1.AuthenticationError(detail, response.status);
+                }
+                if (response.status === 404) {
+                    throw new errors_1.NotFoundError(detail, response.status);
+                }
+                if (response.status === 400 || response.status === 422) {
+                    throw new errors_1.ValidationError(detail, response.status);
+                }
+                if (response.status >= 500) {
+                    throw new errors_1.ServerError(detail, response.status);
+                }
+                throw new errors_1.ComemoError(detail, response.status);
+            }
+            return (await response.json());
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    // ── Core Memory Operations ──────────────────────────────────────────
+    /**
+     * Extract facts from text and store them as memories.
+     *
+     * @param userId - User ID for memory isolation.
+     * @param sessionId - Session ID for context grouping.
+     * @param text - Input text to extract facts from.
+     * @returns Result with status, action, memory_id, links_created, and score.
+     */
+    async addMemory(userId, sessionId, text) {
+        const data = await this.request("POST", "/memory", {
+            body: { user_id: userId, session_id: sessionId, input: text, config: this.config },
+        });
+        return {
+            status: data.status ?? "",
+            action: data.action ?? "",
+            memory_id: data.memory_id ?? null,
+            links_created: data.links_created ?? 0,
+            score: data.score ?? 0,
+        };
+    }
+    /**
+     * Delete a single memory by ID.
+     *
+     * @param memoryId - The memory identifier to delete.
+     * @returns Object with status, memory_id, and deleted flag.
+     */
+    async deleteMemory(memoryId) {
+        return this.request("DELETE", `/memory/${memoryId}`, { params: {} });
+    }
+    /**
+     * Delete all memories for a user.
+     *
+     * @param userId - The user whose memories to delete.
+     * @returns DeleteResult with count of deleted memories.
+     */
+    async deleteUserMemories(userId) {
+        const data = await this.request("DELETE", "/memory", {
+            params: { user_id: userId },
+        });
+        return {
+            status: data.status ?? "",
+            user_id: data.user_id ?? userId,
+            memories_deleted: data.memories_deleted ?? 0,
+        };
+    }
+    /**
+     * Delete all memories for a specific session.
+     *
+     * @param userId - The user ID.
+     * @param sessionId - The session whose memories to delete.
+     * @returns DeleteResult with count of deleted memories.
+     */
+    async deleteSessionMemories(userId, sessionId) {
+        const data = await this.request("DELETE", `/memory/session/${sessionId}`, {
+            params: { user_id: userId },
+        });
+        return {
+            status: data.status ?? "",
+            user_id: data.user_id ?? userId,
+            memories_deleted: data.memories_deleted ?? 0,
+        };
+    }
+    // ── Retrieval ───────────────────────────────────────────────────────
+    /**
+     * Retrieve top memories matching a query (simple mode).
+     *
+     * @param userId - User ID for namespace isolation.
+     * @param sessionId - Current session ID.
+     * @param query - Search query text.
+     * @param topK - Maximum number of results (1-50). Defaults to 5.
+     * @returns RetrieveResult with query, expanded query, and list of memories.
+     */
+    async retrieve(userId, sessionId, query, topK = 5) {
+        const data = await this.request("POST", "/memories/retrieve", {
+            body: { user_id: userId, session_id: sessionId, query, top_k: topK, config: this.config },
+        });
+        const memories = (data.memories ?? []).map((m) => ({
+            memory_id: m.memory_id,
+            fact: m.fact,
+            score: m.score,
+        }));
+        return {
+            query: data.query ?? query,
+            expanded_query: data.expanded_query ?? "",
+            memories,
+        };
+    }
+    /**
+     * Retrieve memories with full scoring details and advanced options.
+     *
+     * @param userId - User ID for namespace isolation.
+     * @param sessionId - Current session ID.
+     * @param query - Search query text.
+     * @param options - Advanced retrieval options.
+     * @returns DetailedRetrieveResult with full scoring breakdown per memory.
+     */
+    async retrieveAdvanced(userId, sessionId, query, options = {}) {
+        const data = await this.request("POST", "/memory/retrieve", {
+            body: {
+                user_id: userId,
+                session_id: sessionId,
+                query,
+                top_k: options.topK ?? 10,
+                expand_context: options.expandContext ?? true,
+                expand_graph: options.expandGraph ?? true,
+                min_score: options.minScore ?? 0.1,
+                reinforce: options.reinforce ?? false,
+                config: this.config,
+            },
+        });
+        const memories = (data.memories ?? []).map((m) => ({
+            memory_id: m.memory_id,
+            fact: m.fact,
+            domain: m.domain ?? "",
+            final_score: m.final_score ?? 0,
+            semantic_similarity: m.semantic_similarity ?? 0,
+            graph_relevance: m.graph_relevance ?? 0,
+            memory_strength: m.memory_strength ?? 0,
+            recency_score: m.recency_score ?? 0,
+            session_boost: m.session_boost ?? 0,
+            source: m.source ?? "",
+            session_id: m.session_id ?? "",
+        }));
+        return {
+            query: data.query ?? query,
+            expanded_query: data.expanded_query ?? "",
+            user_id: data.user_id ?? userId,
+            session_id: data.session_id ?? sessionId,
+            memories,
+            total_candidates: data.total_candidates ?? 0,
+            filtered_count: data.filtered_count ?? 0,
+            retrieval_time_ms: data.retrieval_time_ms ?? 0,
+        };
+    }
+    /**
+     * Retrieve memories and get an LLM-generated summary.
+     *
+     * @param userId - User ID for namespace isolation.
+     * @param sessionId - Current session ID.
+     * @param query - Search query text.
+     * @param topK - Number of memories to summarize (1-20). Defaults to 5.
+     * @returns RetrieveSummaryResult with summary text and supporting memories.
+     */
+    async retrieveSummary(userId, sessionId, query, topK = 5) {
+        const data = await this.request("POST", "/memories/retrieve-summary", {
+            body: { user_id: userId, session_id: sessionId, query, top_k: topK, config: this.config },
+        });
+        const memories = (data.supporting_memories ?? []).map((m) => ({
+            memory_id: m.memory_id,
+            fact: m.fact,
+            score: m.score,
+        }));
+        return {
+            query: data.query ?? query,
+            summary: data.summary ?? "",
+            supporting_memories: memories,
+        };
+    }
+    /**
+     * List user memories across all sessions.
+     *
+     * @param userId - User ID.
+     * @param query - Search query text.
+     * @param topK - Maximum number of results (1-50). Defaults to 10.
+     * @returns RetrieveResult with matching memories across all sessions.
+     */
+    async listMemories(userId, query, topK = 10) {
+        const data = await this.request("GET", "/memories", {
+            params: { user_id: userId, query, top_k: topK },
+        });
+        const memories = (data.memories ?? []).map((m) => ({
+            memory_id: m.memory_id,
+            fact: m.fact,
+            score: m.score,
+        }));
+        return {
+            query: data.query ?? query,
+            expanded_query: data.expanded_query ?? "",
+            memories,
+        };
+    }
+    // ── Maintenance ────────────────────────────────────────────────────
+    /**
+     * Run tenant-scoped maintenance tasks for a user.
+     *
+     * @param userId - User ID to scope maintenance to (required).
+     * @param tasks - Which tasks to run. Defaults to decay + forgetting + summarization.
+     * @param dryRun - If true, only identify but don't modify memories.
+     * @returns MaintenanceResult with per-task results.
+     */
+    async runMaintenance(userId, tasks, dryRun = false) {
+        const body = {
+            user_id: userId,
+            config: this.config,
+            dry_run: dryRun,
+        };
+        if (tasks) {
+            body.tasks = tasks;
+        }
+        const data = await this.request("POST", "/memory/maintenance", { body });
+        return {
+            status: data.status ?? "",
+            user_id: data.user_id ?? userId,
+            dry_run: data.dry_run ?? dryRun,
+            results: data.results ?? {},
+        };
+    }
+    // ── System ──────────────────────────────────────────────────────────
+    /**
+     * Check API health and status.
+     *
+     * @returns HealthResult with status, version, and architecture.
+     */
+    async health() {
+        const data = await this.request("GET", "/health");
+        return {
+            status: data.status ?? "",
+            version: data.version ?? "",
+            architecture: data.architecture ?? "",
+        };
+    }
+}
+exports.MemoryClient = MemoryClient;

package/dist/errors.d.ts

@@ -0,0 +1,22 @@
+/** Base exception for all SDK errors. */
+export declare class ComemoError extends Error {
+    statusCode: number | undefined;
+    response: Record<string, unknown> | undefined;
+    constructor(message: string, statusCode?: number, response?: Record<string, unknown>);
+}
+/** Raised when authentication fails (401/403). */
+export declare class AuthenticationError extends ComemoError {
+    constructor(message: string, statusCode?: number, response?: Record<string, unknown>);
+}
+/** Raised when a resource is not found (404). */
+export declare class NotFoundError extends ComemoError {
+    constructor(message: string, statusCode?: number, response?: Record<string, unknown>);
+}
+/** Raised when the request is invalid (400/422). */
+export declare class ValidationError extends ComemoError {
+    constructor(message: string, statusCode?: number, response?: Record<string, unknown>);
+}
+/** Raised when the server returns a 5xx error. */
+export declare class ServerError extends ComemoError {
+    constructor(message: string, statusCode?: number, response?: Record<string, unknown>);
+}

package/dist/errors.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerError = exports.ValidationError = exports.NotFoundError = exports.AuthenticationError = exports.ComemoError = void 0;
+/** Base exception for all SDK errors. */
+class ComemoError extends Error {
+    statusCode;
+    response;
+    constructor(message, statusCode, response) {
+        super(message);
+        this.name = "ComemoError";
+        this.statusCode = statusCode;
+        this.response = response;
+    }
+}
+exports.ComemoError = ComemoError;
+/** Raised when authentication fails (401/403). */
+class AuthenticationError extends ComemoError {
+    constructor(message, statusCode, response) {
+        super(message, statusCode, response);
+        this.name = "AuthenticationError";
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+/** Raised when a resource is not found (404). */
+class NotFoundError extends ComemoError {
+    constructor(message, statusCode, response) {
+        super(message, statusCode, response);
+        this.name = "NotFoundError";
+    }
+}
+exports.NotFoundError = NotFoundError;
+/** Raised when the request is invalid (400/422). */
+class ValidationError extends ComemoError {
+    constructor(message, statusCode, response) {
+        super(message, statusCode, response);
+        this.name = "ValidationError";
+    }
+}
+exports.ValidationError = ValidationError;
+/** Raised when the server returns a 5xx error. */
+class ServerError extends ComemoError {
+    constructor(message, statusCode, response) {
+        super(message, statusCode, response);
+        this.name = "ServerError";
+    }
+}
+exports.ServerError = ServerError;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { MemoryClient } from "./client";
+export type { TenantConfig, AddMemoryResult, Memory, DetailedMemory, RetrieveResult, DetailedRetrieveResult, RetrieveSummaryResult, DeleteResult, MaintenanceResult, HealthResult, MemoryClientOptions, RetrieveAdvancedOptions, MaintenanceTaskOptions, } from "./types";
+export { ComemoError, AuthenticationError, NotFoundError, ValidationError, ServerError, } from "./errors";

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerError = exports.ValidationError = exports.NotFoundError = exports.AuthenticationError = exports.ComemoError = exports.MemoryClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "MemoryClient", { enumerable: true, get: function () { return client_1.MemoryClient; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "ComemoError", { enumerable: true, get: function () { return errors_1.ComemoError; } });
+Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_1.AuthenticationError; } });
+Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return errors_1.NotFoundError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_1.ValidationError; } });
+Object.defineProperty(exports, "ServerError", { enumerable: true, get: function () { return errors_1.ServerError; } });

package/dist/types.d.ts

@@ -0,0 +1,113 @@
+/** Per-tenant infrastructure configuration. */
+export interface TenantConfig {
+    /** LLM API key (e.g. OpenAI key). */
+    llmApiKey: string;
+    /** LLM model name (e.g. "gpt-4o-mini"). */
+    model?: string;
+    /** Pinecone API key. */
+    pineconeApiKey: string;
+    /** Pinecone index name. */
+    pineconeIndex: string;
+    /** Pinecone namespace (for multi-tenant within one index). */
+    pineconeNamespace?: string;
+    /** Neo4j connection URI (e.g. "neo4j+s://xxx.databases.neo4j.io"). */
+    neo4jUri: string;
+    /** Neo4j username. */
+    neo4jUsername: string;
+    /** Neo4j password. */
+    neo4jPassword: string;
+    /** Neo4j database name (defaults to "neo4j"). */
+    neo4jDatabase?: string;
+}
+/** Result of adding a memory. */
+export interface AddMemoryResult {
+    status: string;
+    action: string;
+    memory_id: string | null;
+    links_created: number;
+    score: number;
+}
+/** A retrieved memory. */
+export interface Memory {
+    memory_id: string;
+    fact: string;
+    score: number;
+}
+/** A retrieved memory with detailed scoring breakdown. */
+export interface DetailedMemory {
+    memory_id: string;
+    fact: string;
+    domain: string;
+    final_score: number;
+    semantic_similarity: number;
+    graph_relevance: number;
+    memory_strength: number;
+    recency_score: number;
+    session_boost: number;
+    source: string;
+    session_id: string;
+}
+/** Result of a simple retrieval. */
+export interface RetrieveResult {
+    query: string;
+    expanded_query: string;
+    memories: Memory[];
+}
+/** Result of an advanced retrieval with full scoring details. */
+export interface DetailedRetrieveResult {
+    query: string;
+    expanded_query: string;
+    user_id: string;
+    session_id: string;
+    memories: DetailedMemory[];
+    total_candidates: number;
+    filtered_count: number;
+    retrieval_time_ms: number;
+}
+/** Result of a retrieval with LLM summary. */
+export interface RetrieveSummaryResult {
+    query: string;
+    summary: string;
+    supporting_memories: Memory[];
+}
+/** Result of a delete operation. */
+export interface DeleteResult {
+    status: string;
+    user_id: string;
+    memories_deleted: number;
+}
+/** Result of a tenant-scoped maintenance run. */
+export interface MaintenanceResult {
+    status: string;
+    user_id: string;
+    dry_run: boolean;
+    results: Record<string, unknown>;
+}
+/** Health check result. */
+export interface HealthResult {
+    status: string;
+    version: string;
+    architecture: string;
+}
+/** Options for the MemoryClient constructor. */
+export interface MemoryClientOptions extends TenantConfig {
+    /** Base URL of the API. Defaults to "https://xvert.io". */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to 30000. */
+    timeout?: number;
+}
+/** Options for advanced retrieval. */
+export interface RetrieveAdvancedOptions {
+    topK?: number;
+    expandContext?: boolean;
+    expandGraph?: boolean;
+    minScore?: number;
+    reinforce?: boolean;
+}
+/** Options for maintenance tasks. */
+export interface MaintenanceTaskOptions {
+    decay?: boolean;
+    forgetting?: boolean;
+    summarization?: boolean;
+    contradiction_check?: boolean;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "comemo",
+  "version": "1.0.0",
+  "description": "Node.js SDK for CoMemo",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "memory",
+    "cognitive",
+    "ai",
+    "sdk"
+  ],
+  "author": "Hasala",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}