@agentier/memory 0.1.0

package/dist/buffer.d.ts

@@ -0,0 +1,87 @@
+import type { MemoryProvider, Message } from '@agentier/core';
+/**
+ * Configuration options for {@link BufferMemory}.
+ */
+export interface BufferMemoryOptions {
+    /**
+     * Maximum number of estimated tokens to retain in the conversation history.
+     * When exceeded, older non-system messages are dropped (FIFO).
+     */
+    maxTokens?: number;
+    /**
+     * Maximum number of messages to retain in the conversation history.
+     * System messages are always preserved; the limit applies to the remainder.
+     */
+    maxMessages?: number;
+    /**
+     * Strategy used when trimming messages that exceed the limits.
+     * Currently only `'fifo'` (first-in, first-out) is supported.
+     */
+    trimStrategy?: 'fifo';
+}
+/**
+ * An in-memory {@link MemoryProvider} that stores conversation history in a
+ * `Map` keyed by session ID. Messages can be automatically trimmed by count
+ * or estimated token budget so the context window stays within bounds.
+ *
+ * @example
+ * ```ts
+ * import { BufferMemory } from '@agentier/memory'
+ *
+ * const memory = new BufferMemory({ maxMessages: 50, maxTokens: 4096 })
+ *
+ * await memory.save('session-1', [
+ *   { role: 'user', content: 'Hello' },
+ *   { role: 'assistant', content: 'Hi there!' },
+ * ])
+ *
+ * const history = await memory.load('session-1')
+ * ```
+ */
+export declare class BufferMemory implements MemoryProvider {
+    /** @internal Map of session IDs to their message arrays. */
+    private sessions;
+    /** @internal Maximum token budget (undefined = unlimited). */
+    private maxTokens;
+    /** @internal Maximum message count (undefined = unlimited). */
+    private maxMessages;
+    /**
+     * Creates a new `BufferMemory` instance.
+     *
+     * @param options - Optional configuration for message limits and trimming.
+     */
+    constructor(options?: BufferMemoryOptions);
+    /**
+     * Loads the conversation history for a given session.
+     *
+     * @param sessionId - Unique identifier for the conversation session.
+     * @returns A shallow copy of the stored messages, or an empty array if the
+     *          session does not exist.
+     */
+    load(sessionId: string): Promise<Message[]>;
+    /**
+     * Saves messages for a session, applying any configured trimming limits
+     * before storing.
+     *
+     * @param sessionId - Unique identifier for the conversation session.
+     * @param messages - The full list of messages to persist.
+     */
+    save(sessionId: string, messages: Message[]): Promise<void>;
+    /**
+     * Removes all stored messages for a session.
+     *
+     * @param sessionId - Unique identifier for the conversation session to clear.
+     */
+    clear(sessionId: string): Promise<void>;
+    /**
+     * Applies the configured `maxMessages` and `maxTokens` limits to a list of
+     * messages. System messages are always preserved; only non-system messages
+     * are subject to trimming (most-recent messages are kept).
+     *
+     * @internal
+     * @param messages - The messages to trim.
+     * @returns A new array containing only the messages that fit within the
+     *          configured limits.
+     */
+    private trimMessages;
+}

package/dist/file.d.ts

@@ -0,0 +1,96 @@
+import type { MemoryProvider, Message } from '@agentier/core';
+/**
+ * Configuration options for {@link FileMemory}.
+ */
+export interface FileMemoryOptions {
+    /**
+     * Path to the storage location. If the path ends with `.json`, all sessions
+     * are stored in that single file (keyed by session ID). Otherwise the path
+     * is treated as a directory and each session gets its own
+     * `<sessionId>.json` file.
+     */
+    path: string;
+    /**
+     * Maximum number of messages to retain per session.
+     * System messages are always preserved; the limit applies to the remainder.
+     */
+    maxMessages?: number;
+}
+/**
+ * A filesystem-backed {@link MemoryProvider} that persists conversation
+ * history as JSON files on disk.
+ *
+ * Two storage modes are supported depending on the `path` option:
+ * - **Directory mode** (`path` does not end with `.json`) -- each session is
+ *   written to its own `<sessionId>.json` file inside the directory.
+ * - **Single-file mode** (`path` ends with `.json`) -- all sessions are
+ *   stored as keys in a single JSON object.
+ *
+ * @example
+ * ```ts
+ * import { FileMemory } from '@agentier/memory'
+ *
+ * // Directory mode -- one file per session
+ * const memory = new FileMemory({ path: './data/sessions' })
+ *
+ * // Single-file mode -- all sessions in one file
+ * const shared = new FileMemory({ path: './data/memory.json', maxMessages: 100 })
+ * ```
+ */
+export declare class FileMemory implements MemoryProvider {
+    /** @internal Absolute or relative base path for storage. */
+    private basePath;
+    /** @internal Whether the provider is operating in directory mode. */
+    private isDirectory;
+    /** @internal Optional cap on persisted message count. */
+    private maxMessages;
+    /**
+     * Creates a new `FileMemory` instance.
+     *
+     * @param options - Configuration specifying the storage path and optional
+     *                  message limit.
+     */
+    constructor(options: FileMemoryOptions);
+    /**
+     * Resolves the on-disk file path for a given session.
+     *
+     * @internal
+     * @param sessionId - The session identifier.
+     * @returns The absolute or relative path to the JSON file.
+     */
+    private getFilePath;
+    /**
+     * Returns the JSON key used to store messages for the session.
+     *
+     * @internal
+     * @param sessionId - The session identifier.
+     * @returns `'messages'` in directory mode, or the session ID in
+     *          single-file mode.
+     */
+    private getStorageKey;
+    /**
+     * Loads the conversation history for a given session from disk.
+     *
+     * @param sessionId - Unique identifier for the conversation session.
+     * @returns The stored messages, or an empty array if the session file does
+     *          not exist or cannot be parsed.
+     */
+    load(sessionId: string): Promise<Message[]>;
+    /**
+     * Persists messages for a session to disk, applying the optional
+     * `maxMessages` limit before writing. Parent directories are created
+     * automatically if they do not exist.
+     *
+     * @param sessionId - Unique identifier for the conversation session.
+     * @param messages - The full list of messages to persist.
+     */
+    save(sessionId: string, messages: Message[]): Promise<void>;
+    /**
+     * Removes conversation history for a session. In directory mode the
+     * session file is deleted; in single-file mode the session key is removed
+     * from the shared JSON object.
+     *
+     * @param sessionId - Unique identifier for the conversation session to clear.
+     */
+    clear(sessionId: string): Promise<void>;
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @module @agentier/memory
+ *
+ * Provides pluggable memory providers for persisting agent conversation
+ * history. Two built-in implementations are included:
+ *
+ * - {@link BufferMemory} -- fast, in-memory storage with optional token/message
+ *   limits.
+ * - {@link FileMemory} -- filesystem-backed storage using JSON files.
+ */
+export { BufferMemory } from './buffer';
+export type { BufferMemoryOptions } from './buffer';
+export { FileMemory } from './file';
+export type { FileMemoryOptions } from './file';

package/dist/index.js

@@ -0,0 +1,134 @@
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/buffer.ts
+function estimateTokens(message) {
+  const content = message.content ?? "";
+  return Math.ceil(content.length / 4);
+}
+
+class BufferMemory {
+  sessions = new Map;
+  maxTokens;
+  maxMessages;
+  constructor(options) {
+    this.maxTokens = options?.maxTokens;
+    this.maxMessages = options?.maxMessages;
+  }
+  async load(sessionId) {
+    return [...this.sessions.get(sessionId) ?? []];
+  }
+  async save(sessionId, messages) {
+    let trimmed = [...messages];
+    trimmed = this.trimMessages(trimmed);
+    this.sessions.set(sessionId, trimmed);
+  }
+  async clear(sessionId) {
+    this.sessions.delete(sessionId);
+  }
+  trimMessages(messages) {
+    let result = [...messages];
+    if (this.maxMessages && result.length > this.maxMessages) {
+      const system = result.filter((m) => m.role === "system");
+      const rest = result.filter((m) => m.role !== "system");
+      const keep = rest.slice(rest.length - (this.maxMessages - system.length));
+      result = [...system, ...keep];
+    }
+    if (this.maxTokens) {
+      const system = result.filter((m) => m.role === "system");
+      const rest = result.filter((m) => m.role !== "system");
+      let totalTokens = system.reduce((sum, m) => sum + estimateTokens(m), 0);
+      const kept = [];
+      for (let i = rest.length - 1;i >= 0; i--) {
+        const msgTokens = estimateTokens(rest[i]);
+        if (totalTokens + msgTokens > this.maxTokens)
+          break;
+        kept.unshift(rest[i]);
+        totalTokens += msgTokens;
+      }
+      result = [...system, ...kept];
+    }
+    return result;
+  }
+}
+// src/file.ts
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { join, dirname } from "path";
+import { existsSync } from "fs";
+
+class FileMemory {
+  basePath;
+  isDirectory;
+  maxMessages;
+  constructor(options) {
+    this.basePath = options.path;
+    this.isDirectory = !options.path.endsWith(".json");
+    this.maxMessages = options.maxMessages;
+  }
+  getFilePath(sessionId) {
+    if (this.isDirectory) {
+      return join(this.basePath, `${sessionId}.json`);
+    }
+    return this.basePath;
+  }
+  getStorageKey(sessionId) {
+    return this.isDirectory ? "messages" : sessionId;
+  }
+  async load(sessionId) {
+    const filePath = this.getFilePath(sessionId);
+    try {
+      const content = await readFile(filePath, "utf-8");
+      const data = JSON.parse(content);
+      if (this.isDirectory) {
+        return Array.isArray(data) ? data : [];
+      }
+      return Array.isArray(data[sessionId]) ? data[sessionId] : [];
+    } catch {
+      return [];
+    }
+  }
+  async save(sessionId, messages) {
+    const filePath = this.getFilePath(sessionId);
+    let trimmed = messages;
+    if (this.maxMessages && messages.length > this.maxMessages) {
+      const system = messages.filter((m) => m.role === "system");
+      const rest = messages.filter((m) => m.role !== "system");
+      trimmed = [...system, ...rest.slice(rest.length - (this.maxMessages - system.length))];
+    }
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+      await mkdir(dir, { recursive: true });
+    }
+    if (this.isDirectory) {
+      await writeFile(filePath, JSON.stringify(trimmed, null, 2), "utf-8");
+    } else {
+      let data = {};
+      try {
+        const content = await readFile(filePath, "utf-8");
+        data = JSON.parse(content);
+      } catch {}
+      data[sessionId] = trimmed;
+      await writeFile(filePath, JSON.stringify(data, null, 2), "utf-8");
+    }
+  }
+  async clear(sessionId) {
+    if (this.isDirectory) {
+      const filePath = this.getFilePath(sessionId);
+      try {
+        const { unlink } = await import("fs/promises");
+        await unlink(filePath);
+      } catch {}
+    } else {
+      try {
+        const content = await readFile(this.basePath, "utf-8");
+        const data = JSON.parse(content);
+        delete data[sessionId];
+        await writeFile(this.basePath, JSON.stringify(data, null, 2), "utf-8");
+      } catch {}
+    }
+  }
+}
+export {
+  FileMemory,
+  BufferMemory
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+    "name": "@agentier/memory",
+    "version": "0.1.0",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "bun build ./src/index.ts --outdir ./dist --target node",
+        "test": "bun test",
+        "typecheck": "tsc --noEmit"
+    },
+    "peerDependencies": {
+        "@agentier/core": "^0.1.0"
+    },
+    "devDependencies": {
+        "@agentier/core": "workspace:*",
+        "typescript": "^5.5.0",
+        "@types/bun": "latest"
+    }
+}