@agnt5/sdk 0.2.1

package/dist/memory.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Memory APIs for AGNT5 agents and workflows.
+ *
+ * Provides:
+ * - ConversationMemory: Message history storage (state-adapter backed)
+ * - SemanticMemory: Vector-backed similarity search (interface + adapter pattern)
+ * - GraphMemory: In-memory knowledge graph with BFS traversal
+ * - MemoryScope: Multi-scope isolation (user, session, agent, tenant, global)
+ */
+import type { StateAdapter } from './state.js';
+/** Memory scope for isolation */
+export declare const MemoryScope: {
+    readonly USER: "user";
+    readonly TENANT: "tenant";
+    readonly AGENT: "agent";
+    readonly SESSION: "session";
+    readonly GLOBAL: "global";
+    readonly validScopes: () => string[];
+    readonly isValid: (scope: string) => boolean;
+    /** Generate collection name for a scope */
+    readonly collectionName: (scope: string, scopeId: string) => string;
+};
+export type MemoryScopeType = 'user' | 'tenant' | 'agent' | 'session' | 'global';
+/** A message in conversation history */
+export interface MemoryMessage {
+    role: string;
+    content: string;
+    timestamp: number;
+    metadata: Record<string, any>;
+}
+/**
+ * Conversation memory backed by a StateAdapter.
+ *
+ * Stores message history per session, suitable for multi-turn conversations.
+ *
+ * @example
+ * ```typescript
+ * const memory = new ConversationMemory('session-123');
+ * await memory.add('user', 'Hello!');
+ * await memory.add('assistant', 'Hi there!');
+ * const messages = await memory.getMessages();
+ * ```
+ */
+export declare class ConversationMemory {
+    private _sessionId;
+    private _adapter;
+    private _storeKey;
+    constructor(sessionId: string, adapter?: StateAdapter);
+    get sessionId(): string;
+    /** Load the current session data */
+    private loadData;
+    /** Save session data */
+    private saveData;
+    /**
+     * Get conversation messages, most recent first.
+     *
+     * @param limit - Maximum number of messages to return (default: 50)
+     */
+    getMessages(limit?: number): Promise<MemoryMessage[]>;
+    /**
+     * Add a message to the conversation.
+     */
+    add(role: string, content: string, metadata?: Record<string, any>): Promise<void>;
+    /** Clear all messages */
+    clear(): Promise<void>;
+    /**
+     * Get messages formatted for LM consumption.
+     *
+     * @param limit - Maximum number of messages to return
+     * @returns Messages as { role, content } objects
+     */
+    getAsLmMessages(limit?: number): Promise<Array<{
+        role: string;
+        content: string;
+    }>>;
+}
+/** Metadata associated with a memory entry */
+export interface MemoryMetadata {
+    source?: string;
+    createdAt?: string;
+    extra: Record<string, string>;
+}
+/** Result from a semantic memory search */
+export interface MemoryResult {
+    id: string;
+    content: string;
+    score: number;
+    metadata: MemoryMetadata;
+}
+/**
+ * Adapter interface for semantic memory backends (embeddings + vector DB).
+ */
+export interface SemanticMemoryAdapter {
+    store(collection: string, content: string, metadata?: MemoryMetadata): Promise<string>;
+    storeBatch(collection: string, contents: string[], metadata?: MemoryMetadata[]): Promise<string[]>;
+    search(collection: string, query: string, limit: number, minScore?: number): Promise<MemoryResult[]>;
+    get(collection: string, memoryId: string): Promise<MemoryResult | null>;
+    forget(collection: string, memoryId: string): Promise<boolean>;
+}
+/**
+ * In-memory semantic memory adapter using simple string similarity.
+ *
+ * Uses word overlap (Jaccard) as a stand-in for real embeddings.
+ * For production, use a real vector DB adapter.
+ */
+export declare class InMemorySemanticAdapter implements SemanticMemoryAdapter {
+    private collections;
+    private getCollection;
+    private tokenize;
+    private jaccard;
+    store(collection: string, content: string, metadata?: MemoryMetadata): Promise<string>;
+    storeBatch(collection: string, contents: string[], metadata?: MemoryMetadata[]): Promise<string[]>;
+    search(collection: string, query: string, limit: number, minScore?: number): Promise<MemoryResult[]>;
+    get(collection: string, memoryId: string): Promise<MemoryResult | null>;
+    forget(collection: string, memoryId: string): Promise<boolean>;
+}
+/**
+ * Semantic memory with vector-backed similarity search.
+ *
+ * @example
+ * ```typescript
+ * const memory = new SemanticMemory('user', 'user-123');
+ * const id = await memory.store('TypeScript is great for type safety');
+ * const results = await memory.search('type checking', 5);
+ * ```
+ */
+export declare class SemanticMemory {
+    private _scope;
+    private _scopeId;
+    private _adapter;
+    private _collection;
+    constructor(scope: MemoryScopeType, scopeId: string, adapter?: SemanticMemoryAdapter);
+    get scope(): MemoryScopeType;
+    get scopeId(): string;
+    get collectionName(): string;
+    /** Store a content string. Returns the memory ID. */
+    store(content: string, metadata?: MemoryMetadata): Promise<string>;
+    /** Store multiple content strings. Returns memory IDs. */
+    storeBatch(contents: string[], metadata?: MemoryMetadata[]): Promise<string[]>;
+    /** Search for similar content. */
+    search(query: string, limit?: number, minScore?: number): Promise<MemoryResult[]>;
+    /** Get a specific memory by ID. */
+    get(memoryId: string): Promise<MemoryResult | null>;
+    /** Delete a memory by ID. */
+    forget(memoryId: string): Promise<boolean>;
+    /**
+     * Create a SemanticMemory backed by real embeddings + vector DB via NAPI.
+     *
+     * Auto-detects embedder and vector DB from environment variables:
+     * - OPENAI_API_KEY → OpenAI embeddings
+     * - QDRANT_URL, PINECONE_API_KEY, etc. → vector DB
+     *
+     * Falls back to InMemorySemanticAdapter if NAPI is unavailable.
+     */
+    static fromEnv(scope: MemoryScopeType, scopeId: string): Promise<SemanticMemory>;
+}
+/** A node in the knowledge graph */
+export interface GraphNode {
+    id: string;
+    nodeType: string;
+    properties: Record<string, string>;
+}
+/** A relationship between two nodes */
+export interface GraphRelationship {
+    id: string;
+    fromNode: string;
+    toNode: string;
+    relationshipType: string;
+    properties: Record<string, string>;
+    createdAt: number;
+}
+/** Result of a graph traversal */
+export interface GraphTraversalResult {
+    startNode: string;
+    nodes: GraphNode[];
+    relationships: GraphRelationship[];
+    depth: number;
+}
+/**
+ * In-memory knowledge graph with BFS traversal.
+ *
+ * @example
+ * ```typescript
+ * const graph = new GraphMemory('user:alice');
+ * await graph.upsertNode('alice', 'User', { name: 'Alice' });
+ * await graph.upsertNode('python', 'Topic', { name: 'Python' });
+ * await graph.relate('alice', 'python', 'likes');
+ *
+ * const result = await graph.traverse('alice', 2);
+ * console.log(result.nodes); // alice + python
+ * ```
+ */
+export declare class GraphMemory {
+    private _scope;
+    private _nodes;
+    private _relationships;
+    private _fromIndex;
+    private _toIndex;
+    private _native;
+    constructor(scope: string);
+    /**
+     * Create a GraphMemory backed by the Rust core via NAPI.
+     * Falls back to in-memory JS implementation if NAPI is unavailable.
+     */
+    static fromNapi(scope: string): GraphMemory;
+    get scope(): string;
+    /** Create or update a node */
+    upsertNode(nodeId: string, nodeType: string, properties?: Record<string, string>): Promise<string>;
+    /** Get a node by ID */
+    getNode(nodeId: string): Promise<GraphNode | null>;
+    /** Delete a node and all its relationships */
+    deleteNode(nodeId: string): Promise<boolean>;
+    /** Create a relationship between two nodes */
+    relate(fromNode: string, toNode: string, relationshipType: string, properties?: Record<string, string>): Promise<string>;
+    /** Query relationships with optional filters */
+    queryRelationships(opts?: {
+        fromNode?: string;
+        toNode?: string;
+        relationshipType?: string;
+        limit?: number;
+    }): Promise<GraphRelationship[]>;
+    /** Delete a relationship by ID */
+    deleteRelationship(relationshipId: string): Promise<boolean>;
+    /**
+     * BFS traversal from a starting node.
+     *
+     * @param startNode - Starting node ID
+     * @param depth - Maximum traversal depth (default: 2)
+     * @param relationshipTypes - Filter by relationship types
+     * @param nodeTypes - Filter by node types
+     */
+    traverse(startNode: string, depth?: number, relationshipTypes?: string[], nodeTypes?: string[]): Promise<GraphTraversalResult>;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"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"}