@betterdb/agent-memory 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026-present BetterDB Inc.
+
+Portions of this software are licensed as follows:
+
+- All content residing under the "doc/" directory of this repository is licensed under the "Creative Commons: CC BY-SA 4.0 license".
+
+- All content that resides under the "proprietary/" directory of this repository, if that directory exists, is licensed under the license defined in "proprietary/LICENSE".
+
+- All third-party components incorporated into the BetterDB Software are licensed under the original license provided by the owner of the applicable component.
+
+- Content outside of the above-mentioned directories or restrictions above is available under the "MIT Expat" license as defined below.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# @betterdb/agent-memory
+
+Standalone agent memory for [Valkey](https://valkey.io/): the short-term caching tiers from [`@betterdb/agent-cache`](../agent-cache/) plus a semantic long-term `MemoryStore` backed by [Valkey Search](https://valkey.io/topics/search/) (`FT.*`). Store memories with `remember()`, retrieve the most relevant ones with `recall()` (semantic similarity blended with recency and importance), and keep stores bounded with TTLs, capacity eviction, and `consolidate()`.
+
+## Installation
+
+```bash
+npm install @betterdb/agent-memory iovalkey
+```
+
+Requires a Valkey server with the [Valkey Search](https://valkey.io/topics/search/) module loaded (for the `FT.*` commands), and an embedding function you provide.
+
+## Quick start
+
+The `AgentMemory` facade wires the short-term cache tiers and the long-term memory store together over a single client and name:
+
+```ts
+import Valkey from 'iovalkey';
+import { AgentMemory } from '@betterdb/agent-memory';
+
+const client = new Valkey('redis://localhost:6379');
+
+const agent = new AgentMemory({
+  client,
+  name: 'my_agent',
+  embedFn: async (text) => embed(text), // returns number[]
+});
+
+// Create the vector index and register discovery markers (idempotent).
+await agent.initialize();
+
+// Long-term memory:
+await agent.memory.remember('User prefers dark mode', {
+  agentId: 'assistant',
+  importance: 0.8,
+  tags: ['preferences'],
+});
+
+const hits = await agent.memory.recall('what theme does the user like?', {
+  agentId: 'assistant',
+  k: 5,
+});
+
+// Short-term cache tiers (from @betterdb/agent-cache):
+agent.llm;
+agent.tool;
+agent.session;
+
+await agent.close();
+```
+
+You can also use the `MemoryStore` directly, without the cache tiers:
+
+```ts
+import { MemoryStore } from '@betterdb/agent-memory';
+
+const memory = new MemoryStore({ client, name: 'my_agent', embedFn });
+await memory.ensureIndex();
+```
+
+## MemoryStore API
+
+- `ensureIndex()` — create the `{name}:mem:idx` vector index if absent (idempotent). Resolves the vector dimension from `embedFn`.
+- `remember(content, options?)` — embed and store a memory; returns its id. Options: `importance` (0..1), `tags`, `ttl` (seconds), and scope (`threadId`, `agentId`, `namespace`).
+- `recall(query, options?)` — semantic search scoped by `threadId`/`agentId`/`namespace`/`tags`, ranked by a composite of similarity, recency (half-life decay), and importance. Returns `MemoryHit[]`. Recalled memories are reinforced (last-access + access-count bumped) unless `reinforce: false`.
+- `forget(id)` — delete a single memory by id.
+- `forgetByScope(scope)` — delete all memories matching a scope and/or tags.
+- `consolidate(options)` — summarize a set of memories (via a `summarize` callback) into one new memory and optionally delete the sources. Select candidates by scope, tags, `olderThanSeconds`, or `maxImportance`.
+- `currentConfig()` / `refreshConfig()` — read the live recall/eviction tunables; with `configRefresh` enabled the store periodically re-reads them from `{name}:__mem_config`.
+- `close()` — stop the config-refresh timer and tear down discovery heartbeats.
+
+### Scoring & capacity
+
+Recall ranks by `compositeScore` — a weighted blend of similarity, recency (true half-life decay), and importance. Defaults are tunable via `MemoryStoreOptions` (`weights`, `halfLifeSeconds`, `defaultThreshold`) or live via config refresh. Set `maxItemsPerScope` to cap memories per scope; over-capacity writes evict the lowest-scoring items (importance + recency).
+
+## Observability
+
+Set `telemetry: { registry }` to register Prometheus metrics (`agent_memory_*`: items, recall total/hits/empty/latency, embedding calls, evictions, consolidations) and OpenTelemetry spans for each operation. With `discovery` enabled (default in the facade), the store publishes a marker to the shared `__betterdb:caches` registry so Monitor can auto-discover it.
+
+## License
+
+MIT

package/dist/AgentMemory.d.ts

@@ -0,0 +1,28 @@
+import { AgentCache, type AgentCacheOptions } from '@betterdb/agent-cache';
+import { MemoryStore, type MemoryDiscoveryConfig, type MemoryConfigRefreshConfig } from './MemoryStore';
+import type { RecallWeights } from './compositeScore';
+import type { EmbedFn } from './types';
+export interface AgentMemoryConfig {
+    defaultThreshold?: number;
+    recall?: {
+        weights?: RecallWeights;
+        halfLifeSeconds?: number;
+    };
+    maxItemsPerScope?: number;
+    discovery?: boolean | MemoryDiscoveryConfig;
+    configRefresh?: boolean | MemoryConfigRefreshConfig;
+}
+export interface AgentMemoryOptions extends AgentCacheOptions {
+    embedFn: EmbedFn;
+    memory?: AgentMemoryConfig;
+}
+export declare class AgentMemory {
+    readonly llm: AgentCache['llm'];
+    readonly tool: AgentCache['tool'];
+    readonly session: AgentCache['session'];
+    readonly memory: MemoryStore;
+    private readonly cache;
+    constructor(options: AgentMemoryOptions);
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/AgentMemory.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentMemory = void 0;
+const agent_cache_1 = require("@betterdb/agent-cache");
+const MemoryStore_1 = require("./MemoryStore");
+const DEFAULT_NAME = 'betterdb_ac';
+class AgentMemory {
+    llm;
+    tool;
+    session;
+    memory;
+    cache;
+    constructor(options) {
+        if (typeof options.embedFn !== 'function') {
+            throw new Error('AgentMemory requires an embedFn to back the memory tier');
+        }
+        // Resolve the name once and hand the same value to both tiers so their key
+        // prefixes, discovery markers, and stats keys can never drift apart.
+        const name = options.name ?? DEFAULT_NAME;
+        this.cache = new agent_cache_1.AgentCache({ ...options, name });
+        this.llm = this.cache.llm;
+        this.tool = this.cache.tool;
+        this.session = this.cache.session;
+        const memory = options.memory ?? {};
+        this.memory = new MemoryStore_1.MemoryStore({
+            // AgentCacheOptions.client doesn't surface the `.call` method MemoryStore
+            // needs; a real ioredis/iovalkey client has it, so we assert the contract
+            // here. A method-only client/mock would compile but fail at runtime.
+            client: options.client,
+            name,
+            embedFn: options.embedFn,
+            defaultThreshold: memory.defaultThreshold,
+            weights: memory.recall?.weights,
+            halfLifeSeconds: memory.recall?.halfLifeSeconds,
+            maxItemsPerScope: memory.maxItemsPerScope,
+            // The facade is the batteries-included product: discover the memory tier
+            // alongside the cache tiers by default, unless explicitly disabled.
+            discovery: memory.discovery ?? true,
+            configRefresh: memory.configRefresh,
+            telemetry: options.telemetry?.registry ? { registry: options.telemetry.registry } : undefined,
+        });
+    }
+    async initialize() {
+        // Create the memory index before discovery so a freshly constructed facade
+        // is immediately usable for remember/recall without the caller hand-rolling
+        // the FT index. A create failure surfaces — the tier is unusable without it.
+        await this.memory.ensureIndex();
+        // Surface a discovery name-collision from either tier: awaiting
+        // ensureDiscoveryReady() is AgentCache's documented strict collision check,
+        // and the memory tier already propagates, so the cache side isn't swallowed.
+        await Promise.all([
+            this.cache.ensureDiscoveryReady(),
+            this.memory.ensureDiscoveryReady(),
+        ]);
+    }
+    async close() {
+        // Tear down both tiers even if one fails, so timers and heartbeats can't leak.
+        try {
+            await this.memory.close();
+        }
+        finally {
+            await this.cache.shutdown();
+        }
+    }
+}
+exports.AgentMemory = AgentMemory;

package/dist/MemoryStore.d.ts

@@ -0,0 +1,81 @@
+import { type RecallWeights } from './compositeScore';
+import { type MemoryTelemetryOptions } from './telemetry';
+import type { ConsolidateOptions, ConsolidateResult, EmbedFn, MemoryHit, MemoryScope, MemoryStoreClient, RecallOptions, RememberOptions } from './types';
+export interface MemoryDiscoveryConfig {
+    version?: string;
+    heartbeatIntervalMs?: number;
+}
+export interface MemoryConfigRefreshConfig {
+    enabled?: boolean;
+    intervalMs?: number;
+}
+export interface MemoryConfigSnapshot {
+    threshold: number;
+    weights: RecallWeights;
+    halfLifeSeconds: number;
+    maxItemsPerScope?: number;
+}
+export interface MemoryStoreOptions {
+    client: MemoryStoreClient;
+    name: string;
+    embedFn: EmbedFn;
+    defaultThreshold?: number;
+    weights?: RecallWeights;
+    halfLifeSeconds?: number;
+    maxItemsPerScope?: number;
+    discovery?: boolean | MemoryDiscoveryConfig;
+    configRefresh?: boolean | MemoryConfigRefreshConfig;
+    telemetry?: MemoryTelemetryOptions;
+}
+export declare class MemoryStore {
+    private readonly client;
+    private readonly name;
+    private readonly embedFn;
+    private defaultThreshold;
+    private weights;
+    private halfLifeSeconds;
+    private maxItemsPerScope?;
+    private readonly initialThreshold;
+    private readonly initialWeights;
+    private readonly initialHalfLifeSeconds;
+    private readonly initialMaxItemsPerScope?;
+    private readonly configKey;
+    private configRefreshHandle;
+    private readonly discovery;
+    private discoveryReady;
+    private readonly telemetry;
+    private readonly storeLabels;
+    private dims?;
+    constructor(options: MemoryStoreOptions);
+    currentConfig(): MemoryConfigSnapshot;
+    refreshConfig(): Promise<void>;
+    private startConfigRefresh;
+    private applyConfig;
+    private createDiscovery;
+    ensureDiscoveryReady(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * Create the `{name}:mem:idx` vector index if it does not already exist.
+     * Idempotent — an existing index is left untouched. Resolves the vector
+     * dimension from `embedFn` when it has not been observed yet. Call once
+     * before the first remember/recall; the AgentMemory facade does this in
+     * initialize().
+     */
+    ensureIndex(): Promise<void>;
+    recall(query: string, options?: RecallOptions): Promise<MemoryHit[]>;
+    private recordRecall;
+    private traced;
+    private reinforce;
+    forget(id: string): Promise<boolean>;
+    forgetByScope(scope: MemoryScope & {
+        tags?: string[];
+    }): Promise<number>;
+    private writeMemory;
+    remember(content: string, options?: RememberOptions): Promise<string>;
+    consolidate(options: ConsolidateOptions): Promise<ConsolidateResult>;
+    private runConsolidate;
+    private writeRecord;
+    private enforceCapacity;
+    private resolveDims;
+    private embed;
+}