agentic-memory 0.1.0

package/dist/adapters/voyageai.d.mts

@@ -0,0 +1,30 @@
+import { E as Embedder } from '../types-CQ8Hcoqw.mjs';
+
+/**
+ * Voyage AI embedder adapter (high-quality, cheaper than OpenAI).
+ * Requires: VOYAGE_API_KEY
+ *
+ * Usage:
+ *   import { AgentMemory } from 'agentic-memory';
+ *   import { VoyageEmbedder } from 'agentic-memory/adapters/voyageai';
+ *
+ *   const memory = new AgentMemory({
+ *     embedder: new VoyageEmbedder({ apiKey: process.env.VOYAGE_API_KEY }),
+ *   });
+ */
+
+interface VoyageEmbedderConfig {
+    apiKey: string;
+    model?: string;
+}
+declare class VoyageEmbedder implements Embedder {
+    private apiKey;
+    private model;
+    constructor(config: VoyageEmbedderConfig);
+    dimensions(): number;
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+    private _call;
+}
+
+export { VoyageEmbedder, type VoyageEmbedderConfig };

package/dist/adapters/voyageai.d.ts

@@ -0,0 +1,30 @@
+import { E as Embedder } from '../types-CQ8Hcoqw.js';
+
+/**
+ * Voyage AI embedder adapter (high-quality, cheaper than OpenAI).
+ * Requires: VOYAGE_API_KEY
+ *
+ * Usage:
+ *   import { AgentMemory } from 'agentic-memory';
+ *   import { VoyageEmbedder } from 'agentic-memory/adapters/voyageai';
+ *
+ *   const memory = new AgentMemory({
+ *     embedder: new VoyageEmbedder({ apiKey: process.env.VOYAGE_API_KEY }),
+ *   });
+ */
+
+interface VoyageEmbedderConfig {
+    apiKey: string;
+    model?: string;
+}
+declare class VoyageEmbedder implements Embedder {
+    private apiKey;
+    private model;
+    constructor(config: VoyageEmbedderConfig);
+    dimensions(): number;
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+    private _call;
+}
+
+export { VoyageEmbedder, type VoyageEmbedderConfig };

package/dist/adapters/voyageai.js

@@ -0,0 +1,64 @@
+"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/adapters/voyageai.ts
+var voyageai_exports = {};
+__export(voyageai_exports, {
+  VoyageEmbedder: () => VoyageEmbedder
+});
+module.exports = __toCommonJS(voyageai_exports);
+var VoyageEmbedder = class {
+  apiKey;
+  model;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.model = config.model ?? "voyage-3-lite";
+  }
+  dimensions() {
+    return this.model.includes("lite") ? 512 : 1024;
+  }
+  async embed(text) {
+    const result = await this._call([text]);
+    return result[0];
+  }
+  async embedBatch(texts) {
+    if (texts.length === 0) return [];
+    return this._call(texts);
+  }
+  async _call(input) {
+    const res = await fetch("https://api.voyageai.com/v1/embeddings", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify({ model: this.model, input })
+    });
+    if (!res.ok) {
+      const err = await res.text();
+      throw new Error(`Voyage AI embedding failed (${res.status}): ${err}`);
+    }
+    const data = await res.json();
+    return data.data.map((d) => d.embedding);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  VoyageEmbedder
+});

package/dist/adapters/voyageai.mjs

@@ -0,0 +1,39 @@
+// src/adapters/voyageai.ts
+var VoyageEmbedder = class {
+  apiKey;
+  model;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.model = config.model ?? "voyage-3-lite";
+  }
+  dimensions() {
+    return this.model.includes("lite") ? 512 : 1024;
+  }
+  async embed(text) {
+    const result = await this._call([text]);
+    return result[0];
+  }
+  async embedBatch(texts) {
+    if (texts.length === 0) return [];
+    return this._call(texts);
+  }
+  async _call(input) {
+    const res = await fetch("https://api.voyageai.com/v1/embeddings", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify({ model: this.model, input })
+    });
+    if (!res.ok) {
+      const err = await res.text();
+      throw new Error(`Voyage AI embedding failed (${res.status}): ${err}`);
+    }
+    const data = await res.json();
+    return data.data.map((d) => d.embedding);
+  }
+};
+export {
+  VoyageEmbedder
+};

package/dist/index.d.mts

@@ -0,0 +1,246 @@
+import { A as AgentMemoryConfig, M as MemoryType, I as ImportanceLevel, a as MemoryEntry, R as RetrievalQuery, b as RetrievalResult, C as ConflictResult, T as TaskNode, c as Checkpoint, D as DecayConfig, S as StorageBackend, E as Embedder, d as RetrievalSignal } from './types-CQ8Hcoqw.mjs';
+export { e as DecayPolicy } from './types-CQ8Hcoqw.mjs';
+
+/**
+ * AgentMemory - the main entry point.
+ *
+ * Framework-agnostic memory layer for AI agents.
+ * Handles storage, multi-signal retrieval, conflict detection,
+ * typed decay, and checkpointing.
+ *
+ * @example
+ * ```typescript
+ * const memory = new AgentMemory();
+ *
+ * await memory.store({
+ *   content: 'User prefers dark mode',
+ *   type: 'preference',
+ *   scope: 'user:123',
+ * });
+ *
+ * const results = await memory.retrieve({ query: 'UI preferences' });
+ * const conflicts = await memory.checkConflicts('User prefers light mode', 'user:123');
+ * ```
+ */
+declare class AgentMemory {
+    private backend;
+    private embedder;
+    private retriever;
+    private conflictDetector;
+    private decayEngine;
+    private checkpoints;
+    private defaultScope;
+    private maxCheckpoints;
+    constructor(config?: AgentMemoryConfig);
+    /**
+     * Store a new memory entry.
+     * Automatically generates ID, timestamps, and embedding.
+     */
+    store(params: {
+        content: string;
+        type?: MemoryType;
+        scope?: string;
+        importance?: ImportanceLevel;
+        confidence?: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<MemoryEntry>;
+    /**
+     * Update an existing memory entry.
+     * Increments version and updates timestamp.
+     */
+    update(id: string, updates: Partial<Pick<MemoryEntry, 'content' | 'type' | 'importance' | 'confidence' | 'metadata'>>): Promise<MemoryEntry | null>;
+    /** Get a memory by ID */
+    get(id: string): Promise<MemoryEntry | null>;
+    /** Delete a memory by ID */
+    delete(id: string): Promise<boolean>;
+    /** Get all memories, optionally filtered by scope */
+    getAll(scope?: string): Promise<MemoryEntry[]>;
+    /** Clear all memories, optionally for a specific scope only */
+    clear(scope?: string): Promise<void>;
+    /**
+     * Multi-signal retrieval.
+     * Combines similarity, recency, importance, and task-relevance.
+     */
+    retrieve(query: RetrievalQuery): Promise<RetrievalResult[]>;
+    /**
+     * Check if content conflicts with stored memories.
+     * Returns conflicts sorted by confidence.
+     *
+     * @example
+     * ```typescript
+     * const conflicts = await memory.checkConflicts('User likes meat', 'user:123');
+     * if (conflicts.length > 0 && conflicts[0].action === 'clarify') {
+     *   // Ask user to confirm preference change
+     * }
+     * ```
+     */
+    checkConflicts(content: string, scope?: string): Promise<ConflictResult[]>;
+    /**
+     * Get the current effective confidence of a memory after decay.
+     */
+    getDecayedConfidence(entry: MemoryEntry): number;
+    /**
+     * Clean up expired memories (decayed below threshold).
+     * Returns the number of deleted entries.
+     */
+    cleanup(scope?: string, threshold?: number): Promise<number>;
+    /**
+     * Create a checkpoint of current task state.
+     * Use this before context overflow to preserve state.
+     */
+    checkpoint(params: {
+        taskGraph: TaskNode[];
+        summary: string;
+        toolOutputs?: Record<string, unknown>;
+        activeMemoryIds?: string[];
+    }): Promise<Checkpoint>;
+    /**
+     * Rehydrate from a checkpoint.
+     * Returns the checkpoint data + relevant memories.
+     */
+    rehydrate(checkpointId: string): Promise<{
+        checkpoint: Checkpoint;
+        memories: MemoryEntry[];
+    } | null>;
+    /** Get the latest checkpoint */
+    getLatestCheckpoint(): Checkpoint | null;
+    /** List all checkpoints */
+    listCheckpoints(): Checkpoint[];
+}
+
+/**
+ * Typed decay engine.
+ * Different memory types decay at different rates.
+ * Hard constraints (allergies, legal requirements) never decay.
+ * Ephemeral task state decays fast.
+ */
+declare class DecayEngine {
+    private config;
+    constructor(config?: Partial<DecayConfig>);
+    /**
+     * Compute the current effective confidence of a memory entry
+     * after applying temporal decay.
+     * Returns a value between 0 and original confidence.
+     */
+    computeDecayedConfidence(entry: MemoryEntry): number;
+    /**
+     * Filter out memories that have decayed below a threshold.
+     * Useful for periodic cleanup.
+     */
+    filterDecayed(entries: MemoryEntry[], threshold?: number): MemoryEntry[];
+    /**
+     * Get entries that should be cleaned up (decayed to near-zero).
+     */
+    getExpired(entries: MemoryEntry[], threshold?: number): MemoryEntry[];
+}
+
+/**
+ * In-memory storage backend. Zero dependencies.
+ * Perfect for development, testing, and single-process agents.
+ * Data is lost when the process exits.
+ */
+declare class LocalStore implements StorageBackend {
+    private entries;
+    get(id: string): Promise<MemoryEntry | null>;
+    getAll(scope?: string): Promise<MemoryEntry[]>;
+    set(entry: MemoryEntry): Promise<void>;
+    delete(id: string): Promise<boolean>;
+    clear(scope?: string): Promise<void>;
+    search(query: RetrievalQuery): Promise<MemoryEntry[]>;
+    /** Get the number of stored entries */
+    get size(): number;
+}
+
+/**
+ * File-based storage backend. Persists to a JSON file on disk.
+ * Good for single-process agents that need persistence across restarts.
+ * Not suitable for concurrent multi-agent access - use Redis/Postgres for that.
+ */
+declare class FileStore implements StorageBackend {
+    private entries;
+    private filePath;
+    private dirty;
+    constructor(filePath: string);
+    private load;
+    private persist;
+    get(id: string): Promise<MemoryEntry | null>;
+    getAll(scope?: string): Promise<MemoryEntry[]>;
+    set(entry: MemoryEntry): Promise<void>;
+    delete(id: string): Promise<boolean>;
+    clear(scope?: string): Promise<void>;
+    search(query: RetrievalQuery): Promise<MemoryEntry[]>;
+    get size(): number;
+}
+
+/**
+ * Multi-signal retriever.
+ * Combines similarity, recency, importance, and task-relevance
+ * into a single ranked result set.
+ */
+declare class MultiSignalRetriever {
+    private store;
+    private embedder;
+    private weights;
+    constructor(store: StorageBackend, embedder: Embedder, weights?: Partial<Record<RetrievalSignal, number>>);
+    retrieve(query: RetrievalQuery): Promise<RetrievalResult[]>;
+}
+
+/**
+ * Conflict detector.
+ * Compares new content against stored memories to find contradictions.
+ * Uses semantic similarity + negation detection, not just keyword matching.
+ */
+declare class ConflictDetector {
+    private store;
+    private embedder;
+    /** Similarity threshold to consider two entries as "same topic" */
+    private topicThreshold;
+    constructor(store: StorageBackend, embedder: Embedder, topicThreshold?: number);
+    /**
+     * Check if new content conflicts with any stored memories.
+     * Returns conflicts sorted by confidence (highest first).
+     */
+    check(content: string, scope?: string): Promise<ConflictResult[]>;
+    /**
+     * Score how contradictory two pieces of text are.
+     * Returns 0 (no contradiction) to 1 (strong contradiction).
+     */
+    private scoreContradiction;
+    /** Check for common antonym pairs */
+    private checkAntonyms;
+    private suggestAction;
+    private generateReason;
+}
+
+/**
+ * Built-in lightweight embedder using bag-of-words TF-IDF.
+ * No external dependencies, no API calls.
+ * Good enough for conflict detection and basic similarity.
+ * For production, plug in OpenAI/Cohere/local embeddings.
+ */
+declare class BuiltinEmbedder implements Embedder {
+    private readonly dim;
+    private vocabulary;
+    private idfCache;
+    private documentCount;
+    private documentFreq;
+    constructor(dimensions?: number);
+    dimensions(): number;
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+    /**
+     * Feed documents to build vocabulary and IDF stats.
+     * Call this when adding memories to improve embedding quality.
+     */
+    train(documents: string[]): void;
+    private tokenize;
+    private tokensToVector;
+    private hashToken;
+}
+
+/** Generate a unique ID */
+declare function generateId(): string;
+/** Cosine similarity between two vectors */
+declare function cosineSimilarity(a: number[], b: number[]): number;
+
+export { AgentMemory, AgentMemoryConfig, BuiltinEmbedder, Checkpoint, ConflictDetector, ConflictResult, DecayConfig, DecayEngine, Embedder, FileStore, ImportanceLevel, LocalStore, MemoryEntry, MemoryType, MultiSignalRetriever, RetrievalQuery, RetrievalResult, RetrievalSignal, StorageBackend, TaskNode, cosineSimilarity, generateId };

package/dist/index.d.ts

@@ -0,0 +1,246 @@
+import { A as AgentMemoryConfig, M as MemoryType, I as ImportanceLevel, a as MemoryEntry, R as RetrievalQuery, b as RetrievalResult, C as ConflictResult, T as TaskNode, c as Checkpoint, D as DecayConfig, S as StorageBackend, E as Embedder, d as RetrievalSignal } from './types-CQ8Hcoqw.js';
+export { e as DecayPolicy } from './types-CQ8Hcoqw.js';
+
+/**
+ * AgentMemory - the main entry point.
+ *
+ * Framework-agnostic memory layer for AI agents.
+ * Handles storage, multi-signal retrieval, conflict detection,
+ * typed decay, and checkpointing.
+ *
+ * @example
+ * ```typescript
+ * const memory = new AgentMemory();
+ *
+ * await memory.store({
+ *   content: 'User prefers dark mode',
+ *   type: 'preference',
+ *   scope: 'user:123',
+ * });
+ *
+ * const results = await memory.retrieve({ query: 'UI preferences' });
+ * const conflicts = await memory.checkConflicts('User prefers light mode', 'user:123');
+ * ```
+ */
+declare class AgentMemory {
+    private backend;
+    private embedder;
+    private retriever;
+    private conflictDetector;
+    private decayEngine;
+    private checkpoints;
+    private defaultScope;
+    private maxCheckpoints;
+    constructor(config?: AgentMemoryConfig);
+    /**
+     * Store a new memory entry.
+     * Automatically generates ID, timestamps, and embedding.
+     */
+    store(params: {
+        content: string;
+        type?: MemoryType;
+        scope?: string;
+        importance?: ImportanceLevel;
+        confidence?: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<MemoryEntry>;
+    /**
+     * Update an existing memory entry.
+     * Increments version and updates timestamp.
+     */
+    update(id: string, updates: Partial<Pick<MemoryEntry, 'content' | 'type' | 'importance' | 'confidence' | 'metadata'>>): Promise<MemoryEntry | null>;
+    /** Get a memory by ID */
+    get(id: string): Promise<MemoryEntry | null>;
+    /** Delete a memory by ID */
+    delete(id: string): Promise<boolean>;
+    /** Get all memories, optionally filtered by scope */
+    getAll(scope?: string): Promise<MemoryEntry[]>;
+    /** Clear all memories, optionally for a specific scope only */
+    clear(scope?: string): Promise<void>;
+    /**
+     * Multi-signal retrieval.
+     * Combines similarity, recency, importance, and task-relevance.
+     */
+    retrieve(query: RetrievalQuery): Promise<RetrievalResult[]>;
+    /**
+     * Check if content conflicts with stored memories.
+     * Returns conflicts sorted by confidence.
+     *
+     * @example
+     * ```typescript
+     * const conflicts = await memory.checkConflicts('User likes meat', 'user:123');
+     * if (conflicts.length > 0 && conflicts[0].action === 'clarify') {
+     *   // Ask user to confirm preference change
+     * }
+     * ```
+     */
+    checkConflicts(content: string, scope?: string): Promise<ConflictResult[]>;
+    /**
+     * Get the current effective confidence of a memory after decay.
+     */
+    getDecayedConfidence(entry: MemoryEntry): number;
+    /**
+     * Clean up expired memories (decayed below threshold).
+     * Returns the number of deleted entries.
+     */
+    cleanup(scope?: string, threshold?: number): Promise<number>;
+    /**
+     * Create a checkpoint of current task state.
+     * Use this before context overflow to preserve state.
+     */
+    checkpoint(params: {
+        taskGraph: TaskNode[];
+        summary: string;
+        toolOutputs?: Record<string, unknown>;
+        activeMemoryIds?: string[];
+    }): Promise<Checkpoint>;
+    /**
+     * Rehydrate from a checkpoint.
+     * Returns the checkpoint data + relevant memories.
+     */
+    rehydrate(checkpointId: string): Promise<{
+        checkpoint: Checkpoint;
+        memories: MemoryEntry[];
+    } | null>;
+    /** Get the latest checkpoint */
+    getLatestCheckpoint(): Checkpoint | null;
+    /** List all checkpoints */
+    listCheckpoints(): Checkpoint[];
+}
+
+/**
+ * Typed decay engine.
+ * Different memory types decay at different rates.
+ * Hard constraints (allergies, legal requirements) never decay.
+ * Ephemeral task state decays fast.
+ */
+declare class DecayEngine {
+    private config;
+    constructor(config?: Partial<DecayConfig>);
+    /**
+     * Compute the current effective confidence of a memory entry
+     * after applying temporal decay.
+     * Returns a value between 0 and original confidence.
+     */
+    computeDecayedConfidence(entry: MemoryEntry): number;
+    /**
+     * Filter out memories that have decayed below a threshold.
+     * Useful for periodic cleanup.
+     */
+    filterDecayed(entries: MemoryEntry[], threshold?: number): MemoryEntry[];
+    /**
+     * Get entries that should be cleaned up (decayed to near-zero).
+     */
+    getExpired(entries: MemoryEntry[], threshold?: number): MemoryEntry[];
+}
+
+/**
+ * In-memory storage backend. Zero dependencies.
+ * Perfect for development, testing, and single-process agents.
+ * Data is lost when the process exits.
+ */
+declare class LocalStore implements StorageBackend {
+    private entries;
+    get(id: string): Promise<MemoryEntry | null>;
+    getAll(scope?: string): Promise<MemoryEntry[]>;
+    set(entry: MemoryEntry): Promise<void>;
+    delete(id: string): Promise<boolean>;
+    clear(scope?: string): Promise<void>;
+    search(query: RetrievalQuery): Promise<MemoryEntry[]>;
+    /** Get the number of stored entries */
+    get size(): number;
+}
+
+/**
+ * File-based storage backend. Persists to a JSON file on disk.
+ * Good for single-process agents that need persistence across restarts.
+ * Not suitable for concurrent multi-agent access - use Redis/Postgres for that.
+ */
+declare class FileStore implements StorageBackend {
+    private entries;
+    private filePath;
+    private dirty;
+    constructor(filePath: string);
+    private load;
+    private persist;
+    get(id: string): Promise<MemoryEntry | null>;
+    getAll(scope?: string): Promise<MemoryEntry[]>;
+    set(entry: MemoryEntry): Promise<void>;
+    delete(id: string): Promise<boolean>;
+    clear(scope?: string): Promise<void>;
+    search(query: RetrievalQuery): Promise<MemoryEntry[]>;
+    get size(): number;
+}
+
+/**
+ * Multi-signal retriever.
+ * Combines similarity, recency, importance, and task-relevance
+ * into a single ranked result set.
+ */
+declare class MultiSignalRetriever {
+    private store;
+    private embedder;
+    private weights;
+    constructor(store: StorageBackend, embedder: Embedder, weights?: Partial<Record<RetrievalSignal, number>>);
+    retrieve(query: RetrievalQuery): Promise<RetrievalResult[]>;
+}
+
+/**
+ * Conflict detector.
+ * Compares new content against stored memories to find contradictions.
+ * Uses semantic similarity + negation detection, not just keyword matching.
+ */
+declare class ConflictDetector {
+    private store;
+    private embedder;
+    /** Similarity threshold to consider two entries as "same topic" */
+    private topicThreshold;
+    constructor(store: StorageBackend, embedder: Embedder, topicThreshold?: number);
+    /**
+     * Check if new content conflicts with any stored memories.
+     * Returns conflicts sorted by confidence (highest first).
+     */
+    check(content: string, scope?: string): Promise<ConflictResult[]>;
+    /**
+     * Score how contradictory two pieces of text are.
+     * Returns 0 (no contradiction) to 1 (strong contradiction).
+     */
+    private scoreContradiction;
+    /** Check for common antonym pairs */
+    private checkAntonyms;
+    private suggestAction;
+    private generateReason;
+}
+
+/**
+ * Built-in lightweight embedder using bag-of-words TF-IDF.
+ * No external dependencies, no API calls.
+ * Good enough for conflict detection and basic similarity.
+ * For production, plug in OpenAI/Cohere/local embeddings.
+ */
+declare class BuiltinEmbedder implements Embedder {
+    private readonly dim;
+    private vocabulary;
+    private idfCache;
+    private documentCount;
+    private documentFreq;
+    constructor(dimensions?: number);
+    dimensions(): number;
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+    /**
+     * Feed documents to build vocabulary and IDF stats.
+     * Call this when adding memories to improve embedding quality.
+     */
+    train(documents: string[]): void;
+    private tokenize;
+    private tokensToVector;
+    private hashToken;
+}
+
+/** Generate a unique ID */
+declare function generateId(): string;
+/** Cosine similarity between two vectors */
+declare function cosineSimilarity(a: number[], b: number[]): number;
+
+export { AgentMemory, AgentMemoryConfig, BuiltinEmbedder, Checkpoint, ConflictDetector, ConflictResult, DecayConfig, DecayEngine, Embedder, FileStore, ImportanceLevel, LocalStore, MemoryEntry, MemoryType, MultiSignalRetriever, RetrievalQuery, RetrievalResult, RetrievalSignal, StorageBackend, TaskNode, cosineSimilarity, generateId };