@betterdb/agent-memory 0.1.0

package/dist/buildMemoryRecord.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMemoryRecord = buildMemoryRecord;
+const valkey_search_kit_1 = require("@betterdb/valkey-search-kit");
+const DEFAULT_IMPORTANCE = 0.5;
+function buildMemoryRecord(name, id, content, vector, options, now) {
+    const importance = options.importance ?? DEFAULT_IMPORTANCE;
+    if (!Number.isFinite(importance) || importance < 0 || importance > 1) {
+        throw new Error(`importance must be a finite number in [0, 1], got: ${String(options.importance)}`);
+    }
+    const fields = [
+        'content',
+        content,
+        'vector',
+        (0, valkey_search_kit_1.encodeFloat32)(vector),
+        'importance',
+        String(importance),
+        'created_at',
+        String(now),
+        'last_accessed_at',
+        String(now),
+        'access_count',
+        '0',
+    ];
+    const tags = options.tags ?? [];
+    for (const tag of tags) {
+        if (tag.includes(',')) {
+            throw new Error(`Tag '${tag}' must not contain a comma; tags are stored comma-separated`);
+        }
+    }
+    if (tags.length > 0) {
+        fields.push('tags', tags.join(','));
+    }
+    if (options.threadId !== undefined) {
+        fields.push('threadId', options.threadId);
+    }
+    if (options.agentId !== undefined) {
+        fields.push('agentId', options.agentId);
+    }
+    if (options.namespace !== undefined) {
+        fields.push('namespace', options.namespace);
+    }
+    if (options.source !== undefined) {
+        fields.push('source', options.source);
+    }
+    return { key: `${name}:mem:${id}`, fields };
+}

package/dist/buildRecallQuery.d.ts

@@ -0,0 +1,11 @@
+import type { MemoryScope } from './types';
+export declare const SCORE_FIELD = "__score";
+export declare const VECTOR_FIELD = "vector";
+export declare function buildScopeFilter(scope: MemoryScope, tags: string[]): string;
+export interface ConsolidateFilterOptions {
+    maxCreatedAt?: number;
+    maxImportance?: number;
+    excludeSource?: string;
+}
+export declare function buildConsolidateFilter(scope: MemoryScope, tags: string[], options: ConsolidateFilterOptions): string;
+export declare function buildRecallQuery(k: number, scope: MemoryScope, tags: string[]): string;

package/dist/buildRecallQuery.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VECTOR_FIELD = exports.SCORE_FIELD = void 0;
+exports.buildScopeFilter = buildScopeFilter;
+exports.buildConsolidateFilter = buildConsolidateFilter;
+exports.buildRecallQuery = buildRecallQuery;
+const valkey_search_kit_1 = require("@betterdb/valkey-search-kit");
+exports.SCORE_FIELD = '__score';
+exports.VECTOR_FIELD = 'vector';
+function scopeClauses(scope, tags) {
+    const clauses = [];
+    if (scope.threadId !== undefined) {
+        clauses.push(`@threadId:{${(0, valkey_search_kit_1.escapeTag)(scope.threadId)}}`);
+    }
+    if (scope.agentId !== undefined) {
+        clauses.push(`@agentId:{${(0, valkey_search_kit_1.escapeTag)(scope.agentId)}}`);
+    }
+    if (scope.namespace !== undefined) {
+        clauses.push(`@namespace:{${(0, valkey_search_kit_1.escapeTag)(scope.namespace)}}`);
+    }
+    for (const tag of tags) {
+        clauses.push(`@tags:{${(0, valkey_search_kit_1.escapeTag)(tag)}}`);
+    }
+    return clauses;
+}
+function joinClauses(clauses) {
+    if (clauses.length === 0) {
+        return '*';
+    }
+    return `(${clauses.join(' ')})`;
+}
+function buildScopeFilter(scope, tags) {
+    return joinClauses(scopeClauses(scope, tags));
+}
+function buildConsolidateFilter(scope, tags, options) {
+    const clauses = scopeClauses(scope, tags);
+    if (options.maxCreatedAt !== undefined) {
+        clauses.push(`@created_at:[-inf ${options.maxCreatedAt}]`);
+    }
+    if (options.maxImportance !== undefined) {
+        clauses.push(`@importance:[-inf ${options.maxImportance}]`);
+    }
+    if (options.excludeSource !== undefined) {
+        clauses.push(`-@source:{${(0, valkey_search_kit_1.escapeTag)(options.excludeSource)}}`);
+    }
+    return joinClauses(clauses);
+}
+function buildRecallQuery(k, scope, tags) {
+    return `${buildScopeFilter(scope, tags)}=>[KNN ${k} @${exports.VECTOR_FIELD} $vec AS ${exports.SCORE_FIELD}]`;
+}

package/dist/compositeScore.d.ts

@@ -0,0 +1,21 @@
+export interface RecallWeights {
+    similarity: number;
+    recency: number;
+    importance: number;
+}
+export interface CompositeScoreParams {
+    similarity: number;
+    ageSeconds: number;
+    importance: number;
+    weights: RecallWeights;
+    halfLifeSeconds: number;
+}
+/** True half-life decay: 1 at age 0, 0.5 at one halfLifeSeconds, approaching 0 beyond. */
+export declare function recencyDecay(ageSeconds: number, halfLifeSeconds: number): number;
+/**
+ * Weighted blend of semantic similarity, recency, and importance.
+ * Recency is a true half-life decay: 0.5 at one halfLifeSeconds.
+ */
+export declare function compositeScore(params: CompositeScoreParams): number;
+/** Map cosine distance (0..2, lower = closer) to a 0..1 similarity score. */
+export declare function similarityFromDistance(distance: number): number;

package/dist/compositeScore.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recencyDecay = recencyDecay;
+exports.compositeScore = compositeScore;
+exports.similarityFromDistance = similarityFromDistance;
+/** True half-life decay: 1 at age 0, 0.5 at one halfLifeSeconds, approaching 0 beyond. */
+function recencyDecay(ageSeconds, halfLifeSeconds) {
+    return Math.exp((-Math.LN2 * ageSeconds) / halfLifeSeconds);
+}
+/**
+ * Weighted blend of semantic similarity, recency, and importance.
+ * Recency is a true half-life decay: 0.5 at one halfLifeSeconds.
+ */
+function compositeScore(params) {
+    const recency = recencyDecay(params.ageSeconds, params.halfLifeSeconds);
+    return (params.weights.similarity * params.similarity +
+        params.weights.recency * recency +
+        params.weights.importance * params.importance);
+}
+/** Map cosine distance (0..2, lower = closer) to a 0..1 similarity score. */
+function similarityFromDistance(distance) {
+    return 1 - distance / 2;
+}

package/dist/discovery.d.ts

@@ -0,0 +1,48 @@
+import type { MemoryStoreClient } from './types';
+export declare const MEMORY_CACHE_TYPE = "agent_memory";
+export declare const MEMORY_CAPABILITIES: string[];
+export interface MemoryMarker {
+    type: typeof MEMORY_CACHE_TYPE;
+    prefix: string;
+    version: string;
+    protocol_version: number;
+    capabilities: string[];
+    stats_key: string;
+    started_at: string;
+    pid?: number;
+    hostname?: string;
+}
+export interface MemoryDiscoveryDeps {
+    client: MemoryStoreClient;
+    name: string;
+    version: string;
+    statsKey: string;
+    heartbeatIntervalMs?: number;
+    onWriteFailed?: () => void;
+}
+export declare class MemoryDiscovery {
+    private readonly client;
+    private readonly name;
+    private readonly version;
+    private readonly statsKey;
+    private readonly heartbeatIntervalMs;
+    private readonly markerField;
+    private readonly heartbeatKey;
+    private readonly startedAt;
+    private readonly onWriteFailed;
+    private heartbeatHandle;
+    private inFlightTick;
+    constructor(deps: MemoryDiscoveryDeps);
+    buildMarker(): MemoryMarker;
+    register(): Promise<void>;
+    stop(opts: {
+        deleteHeartbeat: boolean;
+    }): Promise<void>;
+    tickHeartbeat(): Promise<void>;
+    private startHeartbeat;
+    private writeHeartbeat;
+    private writeMarker;
+    private safeHget;
+    private safeCall;
+    private checkCollision;
+}

package/dist/discovery.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryDiscovery = exports.MEMORY_CAPABILITIES = exports.MEMORY_CACHE_TYPE = void 0;
+const node_os_1 = require("node:os");
+const agent_cache_1 = require("@betterdb/agent-cache");
+exports.MEMORY_CACHE_TYPE = 'agent_memory';
+exports.MEMORY_CAPABILITIES = ['recall', 'consolidate', 'reinforce'];
+class MemoryDiscovery {
+    client;
+    name;
+    version;
+    statsKey;
+    heartbeatIntervalMs;
+    markerField;
+    heartbeatKey;
+    startedAt;
+    onWriteFailed;
+    heartbeatHandle = null;
+    inFlightTick = null;
+    constructor(deps) {
+        this.client = deps.client;
+        this.name = deps.name;
+        this.version = deps.version;
+        this.statsKey = deps.statsKey;
+        this.heartbeatIntervalMs = deps.heartbeatIntervalMs ?? agent_cache_1.DEFAULT_HEARTBEAT_INTERVAL_MS;
+        // Namespace the marker under `{name}:mem` so a memory store and an
+        // agent-cache sharing the same name register distinct registry fields and
+        // heartbeat keys instead of clobbering each other.
+        this.markerField = `${deps.name}:mem`;
+        this.heartbeatKey = `${agent_cache_1.HEARTBEAT_KEY_PREFIX}${this.markerField}`;
+        this.startedAt = new Date().toISOString();
+        this.onWriteFailed = deps.onWriteFailed ?? (() => { });
+    }
+    buildMarker() {
+        const marker = {
+            type: exports.MEMORY_CACHE_TYPE,
+            prefix: this.name,
+            version: this.version,
+            protocol_version: agent_cache_1.PROTOCOL_VERSION,
+            capabilities: [...exports.MEMORY_CAPABILITIES],
+            stats_key: this.statsKey,
+            started_at: this.startedAt,
+            pid: process.pid,
+            hostname: (0, node_os_1.hostname)(),
+        };
+        return marker;
+    }
+    async register() {
+        // HGET-then-HSET is not atomic (TOCTOU); acceptable for best-effort
+        // discovery — a racing writer just means last-writer-wins on the marker.
+        const existing = await this.safeHget();
+        if (existing !== null) {
+            this.checkCollision(existing);
+        }
+        await this.writeMarker();
+        await this.safeCall(() => this.client.call('SET', agent_cache_1.PROTOCOL_KEY, String(agent_cache_1.PROTOCOL_VERSION), 'NX'));
+        await this.writeHeartbeat();
+        this.startHeartbeat();
+    }
+    async stop(opts) {
+        if (this.heartbeatHandle) {
+            clearInterval(this.heartbeatHandle);
+            this.heartbeatHandle = null;
+        }
+        // Wait out a tick already in flight so its heartbeat/marker writes can't
+        // land after the DEL below and make the store look alive post-shutdown.
+        if (this.inFlightTick) {
+            await this.inFlightTick;
+        }
+        if (!opts.deleteHeartbeat) {
+            return;
+        }
+        try {
+            await this.client.call('DEL', this.heartbeatKey);
+        }
+        catch {
+            this.onWriteFailed();
+        }
+    }
+    async tickHeartbeat() {
+        await this.writeHeartbeat();
+        await this.writeMarker();
+        // PROTOCOL_KEY is set once in register(); the NX SET is a guaranteed no-op
+        // on every subsequent tick, so it's not re-issued from the heartbeat path.
+    }
+    startHeartbeat() {
+        const handle = setInterval(() => {
+            this.inFlightTick = this.tickHeartbeat()
+                .catch(() => undefined)
+                .finally(() => {
+                this.inFlightTick = null;
+            });
+        }, this.heartbeatIntervalMs);
+        handle.unref?.();
+        this.heartbeatHandle = handle;
+    }
+    async writeHeartbeat() {
+        try {
+            await this.client.call('SET', this.heartbeatKey, new Date().toISOString(), 'EX', String(agent_cache_1.HEARTBEAT_TTL_SECONDS));
+        }
+        catch {
+            this.onWriteFailed();
+        }
+    }
+    async writeMarker() {
+        let payload;
+        try {
+            payload = JSON.stringify(this.buildMarker());
+        }
+        catch {
+            this.onWriteFailed();
+            return;
+        }
+        await this.safeCall(() => this.client.call('HSET', agent_cache_1.REGISTRY_KEY, this.markerField, payload));
+    }
+    async safeHget() {
+        try {
+            const value = await this.client.call('HGET', agent_cache_1.REGISTRY_KEY, this.markerField);
+            return value === null || value === undefined ? null : String(value);
+        }
+        catch {
+            this.onWriteFailed();
+            return null;
+        }
+    }
+    async safeCall(fn) {
+        try {
+            await fn();
+        }
+        catch {
+            this.onWriteFailed();
+        }
+    }
+    checkCollision(existingJson) {
+        let parsed;
+        try {
+            parsed = JSON.parse(existingJson);
+        }
+        catch {
+            return;
+        }
+        if (parsed.type && parsed.type !== exports.MEMORY_CACHE_TYPE) {
+            // Reachable only if a non-agent_memory marker already occupies this field.
+            // The memory marker lives under `{name}:mem`, distinct from agent-cache's
+            // `{name}`, so the two tiers never collide here. Surface it with a visible
+            // warning rather than throwing into a swallowed registration promise;
+            // registration then proceeds last-writer-wins, matching agent-cache.
+            console.warn(`agent-memory discovery: field '${this.markerField}' already holds a '${parsed.type}' marker; overwriting`);
+        }
+    }
+}
+exports.MemoryDiscovery = MemoryDiscovery;

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from '@betterdb/agent-cache';
+export { MemoryStore } from './MemoryStore';
+export type { MemoryStoreOptions, MemoryDiscoveryConfig, MemoryConfigRefreshConfig, MemoryConfigSnapshot, } from './MemoryStore';
+export { MemoryDiscovery, MEMORY_CACHE_TYPE, MEMORY_CAPABILITIES } from './discovery';
+export type { MemoryDiscoveryDeps, MemoryMarker } from './discovery';
+export { createMemoryTelemetry, DEFAULT_METRICS_PREFIX, DEFAULT_TRACER_NAME } from './telemetry';
+export type { MemoryTelemetry, MemoryTelemetryOptions, MemoryMetrics } from './telemetry';
+export { AgentMemory } from './AgentMemory';
+export type { AgentMemoryOptions, AgentMemoryConfig } from './AgentMemory';
+export type { EmbedFn, MemoryStoreClient, MemoryScope, RememberOptions, MemoryItem, RecallOptions, MemoryHit, ConsolidateOptions, ConsolidateResult, } from './types';
+export { compositeScore, similarityFromDistance } from './compositeScore';
+export type { RecallWeights, CompositeScoreParams } from './compositeScore';

package/dist/index.js

@@ -0,0 +1,33 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.similarityFromDistance = exports.compositeScore = exports.AgentMemory = exports.DEFAULT_TRACER_NAME = exports.DEFAULT_METRICS_PREFIX = exports.createMemoryTelemetry = exports.MEMORY_CAPABILITIES = exports.MEMORY_CACHE_TYPE = exports.MemoryDiscovery = exports.MemoryStore = void 0;
+__exportStar(require("@betterdb/agent-cache"), exports);
+var MemoryStore_1 = require("./MemoryStore");
+Object.defineProperty(exports, "MemoryStore", { enumerable: true, get: function () { return MemoryStore_1.MemoryStore; } });
+var discovery_1 = require("./discovery");
+Object.defineProperty(exports, "MemoryDiscovery", { enumerable: true, get: function () { return discovery_1.MemoryDiscovery; } });
+Object.defineProperty(exports, "MEMORY_CACHE_TYPE", { enumerable: true, get: function () { return discovery_1.MEMORY_CACHE_TYPE; } });
+Object.defineProperty(exports, "MEMORY_CAPABILITIES", { enumerable: true, get: function () { return discovery_1.MEMORY_CAPABILITIES; } });
+var telemetry_1 = require("./telemetry");
+Object.defineProperty(exports, "createMemoryTelemetry", { enumerable: true, get: function () { return telemetry_1.createMemoryTelemetry; } });
+Object.defineProperty(exports, "DEFAULT_METRICS_PREFIX", { enumerable: true, get: function () { return telemetry_1.DEFAULT_METRICS_PREFIX; } });
+Object.defineProperty(exports, "DEFAULT_TRACER_NAME", { enumerable: true, get: function () { return telemetry_1.DEFAULT_TRACER_NAME; } });
+var AgentMemory_1 = require("./AgentMemory");
+Object.defineProperty(exports, "AgentMemory", { enumerable: true, get: function () { return AgentMemory_1.AgentMemory; } });
+var compositeScore_1 = require("./compositeScore");
+Object.defineProperty(exports, "compositeScore", { enumerable: true, get: function () { return compositeScore_1.compositeScore; } });
+Object.defineProperty(exports, "similarityFromDistance", { enumerable: true, get: function () { return compositeScore_1.similarityFromDistance; } });

package/dist/parseMemoryItem.d.ts

@@ -0,0 +1,3 @@
+import type { FtSearchHit } from '@betterdb/valkey-search-kit';
+import type { MemoryItem } from './types';
+export declare function parseMemoryItem(name: string, hit: FtSearchHit): MemoryItem;

package/dist/parseMemoryItem.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseMemoryItem = parseMemoryItem;
+function parseMemoryItem(name, hit) {
+    const prefix = `${name}:mem:`;
+    let id = hit.key;
+    if (hit.key.startsWith(prefix)) {
+        id = hit.key.slice(prefix.length);
+    }
+    const fields = hit.fields;
+    const item = {
+        id,
+        content: fields.content ?? '',
+        importance: parseFloat(fields.importance ?? '0'),
+        tags: fields.tags ? fields.tags.split(',') : [],
+        createdAt: parseInt(fields.created_at ?? '0', 10),
+        lastAccessedAt: parseInt(fields.last_accessed_at ?? '0', 10),
+        accessCount: parseInt(fields.access_count ?? '0', 10),
+    };
+    if (fields.source !== undefined) {
+        item.source = fields.source;
+    }
+    if (fields.threadId !== undefined) {
+        item.threadId = fields.threadId;
+    }
+    if (fields.agentId !== undefined) {
+        item.agentId = fields.agentId;
+    }
+    if (fields.namespace !== undefined) {
+        item.namespace = fields.namespace;
+    }
+    return item;
+}

package/dist/selectEvictions.d.ts

@@ -0,0 +1,17 @@
+import { type RecallWeights } from './compositeScore';
+export interface EvictionCandidate {
+    key: string;
+    importance: number;
+    lastAccessedAt: number;
+}
+export interface SelectEvictionsOptions {
+    now: number;
+    halfLifeSeconds: number;
+    weights: RecallWeights;
+}
+/**
+ * Pick the keys to evict so that `maxItems` remain. Eviction blends importance
+ * with last-access recency (the recall weights, minus similarity, renormalized);
+ * lowest-scoring keys go first, ties broken toward the older last-access.
+ */
+export declare function selectEvictions(candidates: EvictionCandidate[], maxItems: number, options: SelectEvictionsOptions): string[];

package/dist/selectEvictions.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectEvictions = selectEvictions;
+const compositeScore_1 = require("./compositeScore");
+function evictionScore(candidate, options) {
+    const { weights } = options;
+    const denom = weights.importance + weights.recency;
+    if (denom === 0) {
+        return 0;
+    }
+    const ageSeconds = (options.now - candidate.lastAccessedAt) / 1000;
+    const recency = (0, compositeScore_1.recencyDecay)(ageSeconds, options.halfLifeSeconds);
+    return (weights.importance * candidate.importance + weights.recency * recency) / denom;
+}
+/**
+ * Pick the keys to evict so that `maxItems` remain. Eviction blends importance
+ * with last-access recency (the recall weights, minus similarity, renormalized);
+ * lowest-scoring keys go first, ties broken toward the older last-access.
+ */
+function selectEvictions(candidates, maxItems, options) {
+    const dropCount = candidates.length - Math.max(0, maxItems);
+    if (dropCount <= 0) {
+        return [];
+    }
+    const ranked = candidates
+        .map((candidate) => ({
+        key: candidate.key,
+        score: evictionScore(candidate, options),
+        lastAccessedAt: candidate.lastAccessedAt,
+    }))
+        .sort((a, b) => a.score !== b.score ? a.score - b.score : a.lastAccessedAt - b.lastAccessedAt);
+    return ranked.slice(0, dropCount).map((entry) => entry.key);
+}

package/dist/telemetry.d.ts

@@ -0,0 +1,24 @@
+import { type Tracer } from '@opentelemetry/api';
+import { Counter, Gauge, Histogram, Registry } from 'prom-client';
+export declare const DEFAULT_METRICS_PREFIX = "agent_memory";
+export declare const DEFAULT_TRACER_NAME = "@betterdb/agent-memory";
+export interface MemoryTelemetryOptions {
+    tracerName?: string;
+    metricsPrefix?: string;
+    registry?: Registry;
+}
+export interface MemoryMetrics {
+    items: Gauge<string>;
+    recallTotal: Counter<string>;
+    recallHits: Counter<string>;
+    recallEmpty: Counter<string>;
+    recallLatency: Histogram<string>;
+    embeddingCalls: Counter<string>;
+    evictions: Counter<string>;
+    consolidations: Counter<string>;
+}
+export interface MemoryTelemetry {
+    tracer: Tracer;
+    metrics: MemoryMetrics;
+}
+export declare function createMemoryTelemetry(options?: MemoryTelemetryOptions): MemoryTelemetry;

package/dist/telemetry.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TRACER_NAME = exports.DEFAULT_METRICS_PREFIX = void 0;
+exports.createMemoryTelemetry = createMemoryTelemetry;
+const api_1 = require("@opentelemetry/api");
+const prom_client_1 = require("prom-client");
+exports.DEFAULT_METRICS_PREFIX = 'agent_memory';
+exports.DEFAULT_TRACER_NAME = '@betterdb/agent-memory';
+const RECALL_LATENCY_BUCKETS = [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0];
+function getOrCreateCounter(registry, config) {
+    const existing = registry.getSingleMetric(config.name);
+    return existing
+        ? existing
+        : new prom_client_1.Counter({ ...config, registers: [registry] });
+}
+function getOrCreateGauge(registry, config) {
+    const existing = registry.getSingleMetric(config.name);
+    return existing ? existing : new prom_client_1.Gauge({ ...config, registers: [registry] });
+}
+function getOrCreateHistogram(registry, config) {
+    const existing = registry.getSingleMetric(config.name);
+    return existing
+        ? existing
+        : new prom_client_1.Histogram({ ...config, registers: [registry] });
+}
+function createMemoryTelemetry(options = {}) {
+    const registry = options.registry ?? prom_client_1.register;
+    const prefix = options.metricsPrefix ?? exports.DEFAULT_METRICS_PREFIX;
+    const tracer = api_1.trace.getTracer(options.tracerName ?? exports.DEFAULT_TRACER_NAME);
+    const labelNames = ['store_name'];
+    return {
+        tracer,
+        metrics: {
+            items: getOrCreateGauge(registry, {
+                name: `${prefix}_items`,
+                help: 'Approximate number of stored memories observed in-process',
+                labelNames,
+            }),
+            recallTotal: getOrCreateCounter(registry, {
+                name: `${prefix}_recall_total`,
+                help: 'Total recall queries',
+                labelNames,
+            }),
+            recallHits: getOrCreateCounter(registry, {
+                name: `${prefix}_recall_hits_total`,
+                help: 'Recall queries that returned at least one memory',
+                labelNames,
+            }),
+            recallEmpty: getOrCreateCounter(registry, {
+                name: `${prefix}_recall_empty_total`,
+                help: 'Recall queries that returned no memories',
+                labelNames,
+            }),
+            recallLatency: getOrCreateHistogram(registry, {
+                name: `${prefix}_recall_latency_seconds`,
+                help: 'Recall query latency in seconds',
+                labelNames,
+                buckets: RECALL_LATENCY_BUCKETS,
+            }),
+            embeddingCalls: getOrCreateCounter(registry, {
+                name: `${prefix}_embedding_calls_total`,
+                help: 'Total embedding function invocations',
+                labelNames,
+            }),
+            evictions: getOrCreateCounter(registry, {
+                name: `${prefix}_evictions_total`,
+                help: 'Total memories evicted for capacity',
+                labelNames,
+            }),
+            consolidations: getOrCreateCounter(registry, {
+                name: `${prefix}_consolidations_total`,
+                help: 'Total consolidation summaries created',
+                labelNames,
+            }),
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+import type { RecallWeights } from './compositeScore';
+export type EmbedFn = (text: string) => Promise<number[]>;
+export interface MemoryStoreClient {
+    call(command: string, ...args: (string | Buffer | number)[]): Promise<unknown>;
+}
+export interface MemoryScope {
+    threadId?: string;
+    agentId?: string;
+    namespace?: string;
+}
+export interface RememberOptions extends MemoryScope {
+    importance?: number;
+    tags?: string[];
+    source?: string;
+    ttl?: number;
+}
+export interface MemoryItem extends MemoryScope {
+    id: string;
+    content: string;
+    importance: number;
+    tags: string[];
+    source?: string;
+    createdAt: number;
+    lastAccessedAt: number;
+    accessCount: number;
+}
+export interface RecallOptions extends MemoryScope {
+    k?: number;
+    threshold?: number;
+    tags?: string[];
+    weights?: RecallWeights;
+    reinforce?: boolean;
+}
+export interface MemoryHit {
+    item: MemoryItem;
+    /**
+     * Raw KNN vector **distance** (cosine), not a similarity: lower means closer
+     * (a perfect match approaches 0). Despite the field name, do not assume
+     * higher is better — sort ascending if ranking by this alone. The composite
+     * `score` (higher is better) is the field to rank recall results by.
+     */
+    similarity: number;
+    /** Composite recall score (similarity + recency + importance); higher is better. */
+    score: number;
+}
+export interface ConsolidateOptions extends MemoryScope {
+    olderThanSeconds?: number;
+    maxImportance?: number;
+    summarize: (items: MemoryItem[]) => Promise<string>;
+    deleteSources?: boolean;
+    summaryImportance?: number;
+    tags?: string[];
+}
+export interface ConsolidateResult {
+    consolidated: number;
+    created: string[];
+    deleted: number;
+}

package/dist/types.js

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