@rine-kit/agent-memory 0.0.0-stage → 0.1.0

package/dist/recall/service.js

@@ -0,0 +1,146 @@
+import { createMemoryUsageSignals } from '../signals.js';
+import { fuseMemoryCandidates } from './fusion.js';
+const DEFAULT_TOP_K = 6;
+const DEFAULT_CANDIDATE_LIMIT = 20;
+const DEFAULT_SEMANTIC_THRESHOLD = 0.72;
+const DEFAULT_MINIMUM_SCORE = 0.005;
+function fallbackContext(candidates) {
+    if (!candidates.length)
+        return null;
+    return JSON.stringify(candidates.map((candidate) => ({
+        key: candidate.key,
+        content: candidate.content,
+        recordedAt: candidate.updatedAt,
+        source: candidate.sourceKind,
+        revision: candidate.revision,
+    })));
+}
+function settled(result, fallback) {
+    return result.status === 'fulfilled' ? result.value : fallback;
+}
+function candidateSourcesFailed(exactFailed, lexicalFailed, semanticFailed, semanticReason) {
+    return exactFailed && lexicalFailed && (semanticFailed || semanticReason !== null);
+}
+/** Generic authorization-fenced recall orchestration; the host supplies scoped storage and rendering. */
+export class MemoryRecallService {
+    storage;
+    options;
+    topK;
+    candidateLimit;
+    semanticSimilarityThreshold;
+    minimumScore;
+    now;
+    constructor(storage, options = {}) {
+        this.storage = storage;
+        this.options = options;
+        this.topK = options.topK ?? DEFAULT_TOP_K;
+        this.candidateLimit = options.candidateLimit ?? DEFAULT_CANDIDATE_LIMIT;
+        this.semanticSimilarityThreshold =
+            options.semanticSimilarityThreshold ?? DEFAULT_SEMANTIC_THRESHOLD;
+        this.minimumScore = options.minimumScore ?? DEFAULT_MINIMUM_SCORE;
+        this.now = options.now ?? Date.now;
+        if (!Number.isSafeInteger(this.topK) ||
+            this.topK < 5 ||
+            this.topK > 8 ||
+            !Number.isSafeInteger(this.candidateLimit) ||
+            this.candidateLimit < this.topK ||
+            this.candidateLimit > 24 ||
+            !Number.isFinite(this.semanticSimilarityThreshold) ||
+            this.semanticSimilarityThreshold < -1 ||
+            this.semanticSimilarityThreshold > 1 ||
+            !Number.isFinite(this.minimumScore) ||
+            this.minimumScore < 0 ||
+            this.minimumScore > 1) {
+            throw new Error('memory_retrieval_limits_invalid');
+        }
+    }
+    report(startedAt, result, counts) {
+        try {
+            this.options.onMetric?.({
+                mode: result.mode,
+                reason: result.reason,
+                durationMs: Math.max(0, this.now() - startedAt),
+                candidateCount: result.candidates.length,
+                exactCount: counts.exact,
+                lexicalCount: counts.lexical,
+                semanticCount: counts.semantic,
+            });
+        }
+        catch {
+            /* metrics never change recall */
+        }
+        return result;
+    }
+    async recall(authorization, query, limit = this.candidateLimit) {
+        const startedAt = this.now();
+        const counts = { exact: 0, lexical: 0, semantic: 0 };
+        if (typeof query !== 'string' || !query.trim()) {
+            return this.report(startedAt, { mode: 'disabled', reason: 'memory_store_unavailable', candidates: [], context: null }, counts);
+        }
+        if (!Number.isSafeInteger(limit) || limit < this.topK || limit > 24) {
+            return this.report(startedAt, { mode: 'disabled', reason: 'memory_store_unavailable', candidates: [], context: null }, counts);
+        }
+        try {
+            return await this.storage.withAuthorizedSearch(authorization, async (searches) => {
+                const results = await Promise.allSettled([
+                    searches.exact(query, limit),
+                    searches.lexical(query, limit),
+                    searches.semantic(query, limit),
+                ]);
+                const exactResult = results[0];
+                const lexicalResult = results[1];
+                const semanticResult = results[2];
+                const exact = settled(exactResult, []);
+                const lexical = settled(lexicalResult, []);
+                const semantic = settled(semanticResult, {
+                    matches: [],
+                    reason: 'semantic_unavailable',
+                });
+                counts.exact = exact.length;
+                counts.lexical = lexical.length;
+                counts.semantic = semantic.matches.length;
+                const candidates = fuseMemoryCandidates(query, exact, lexical, semantic.matches, {
+                    topK: this.topK,
+                    semanticSimilarityThreshold: this.semanticSimilarityThreshold,
+                    minimumScore: this.minimumScore,
+                });
+                const allSourcesFailed = candidateSourcesFailed(exactResult.status === 'rejected', lexicalResult.status === 'rejected', semanticResult.status === 'rejected', semantic.reason);
+                const eitherCandidateSourceFailed = exactResult.status === 'rejected' || lexicalResult.status === 'rejected';
+                const mode = allSourcesFailed
+                    ? 'disabled'
+                    : semantic.reason === null
+                        ? 'hybrid'
+                        : 'lexical_only';
+                const reason = allSourcesFailed
+                    ? 'memory_store_unavailable'
+                    : eitherCandidateSourceFailed
+                        ? 'memory_candidate_source_unavailable'
+                        : semantic.reason;
+                const visible = mode === 'disabled' ? [] : candidates;
+                const result = {
+                    mode,
+                    reason,
+                    candidates: visible,
+                    context: visible.length ? (this.options.renderContext ?? fallbackContext)(visible) : null,
+                };
+                if (result.candidates.length) {
+                    try {
+                        const signals = createMemoryUsageSignals(query, result.candidates);
+                        await this.storage.recordUsageSignals(authorization, 'recalled', signals);
+                    }
+                    catch {
+                        /* usage evidence must never change recall */
+                    }
+                }
+                return this.report(startedAt, result, counts);
+            });
+        }
+        catch {
+            return this.report(startedAt, { mode: 'disabled', reason: 'memory_scope_unavailable', candidates: [], context: null }, counts);
+        }
+    }
+    async recordUsed(authorization, query, candidates) {
+        const signals = createMemoryUsageSignals(query, candidates);
+        await this.storage.recordUsageSignals(authorization, 'used', signals);
+    }
+}

package/dist/runtime.d.ts

@@ -0,0 +1,38 @@
+import type { DreamingReport, ExplicitMemoryWrite, MemoryFeatureFlags, MemoryForgetRequest, MemoryHealth, MemoryObservation, MemoryRecallRequest, MemoryRecallResult, MemoryRetrievedCandidate, MemoryWriteResult } from './contracts.js';
+import type { AgentMemoryPlugin } from './plugin.js';
+export interface MemoryRuntimeRecallPort<TAuthorization> {
+    recall(authorization: TAuthorization, request: MemoryRecallRequest): Promise<MemoryRecallResult>;
+    recordUsed(authorization: TAuthorization, query: string, candidates: readonly MemoryRetrievedCandidate[]): Promise<void>;
+}
+export interface MemoryRuntimeWritePort<TAuthorization> {
+    remember(authorization: TAuthorization, write: ExplicitMemoryWrite): Promise<MemoryWriteResult>;
+    forget(authorization: TAuthorization, request: MemoryForgetRequest): Promise<MemoryWriteResult>;
+}
+export interface MemoryRuntimeAdapters<TAuthorization> {
+    observe: ((authorization: TAuthorization, observation: MemoryObservation) => Promise<void>) | null;
+    recall: MemoryRuntimeRecallPort<TAuthorization> | null;
+    writes: MemoryRuntimeWritePort<TAuthorization> | null;
+    runDreaming: ((signal: AbortSignal) => Promise<DreamingReport>) | null;
+}
+export interface AgentMemoryRuntimeOptions<TAuthorization> {
+    features?: Partial<MemoryFeatureFlags>;
+    adapters: MemoryRuntimeAdapters<TAuthorization>;
+    now?: () => Date;
+}
+/** Generic feature-gated memory runtime; all identity and persistence remain in host adapters. */
+export declare class AgentMemoryRuntime<TAuthorization> implements AgentMemoryPlugin<TAuthorization> {
+    private readonly options;
+    readonly features: Readonly<MemoryFeatureFlags>;
+    private lastDreamingAt;
+    private lastFailureCode;
+    private readonly now;
+    constructor(options: AgentMemoryRuntimeOptions<TAuthorization>);
+    get autoLearnEnabled(): boolean;
+    observe(authorization: TAuthorization, observation: MemoryObservation): Promise<void>;
+    recall(authorization: TAuthorization, request: MemoryRecallRequest): Promise<MemoryRecallResult>;
+    remember(authorization: TAuthorization, write: ExplicitMemoryWrite): Promise<MemoryWriteResult>;
+    forget(authorization: TAuthorization, request: MemoryForgetRequest): Promise<MemoryWriteResult>;
+    recordUsed(authorization: TAuthorization, query: string, candidates: readonly MemoryRetrievedCandidate[]): Promise<void>;
+    runDreaming(signal?: AbortSignal): Promise<DreamingReport>;
+    health(): Promise<MemoryHealth>;
+}

package/dist/runtime.js

@@ -0,0 +1,86 @@
+import { MEMORY_FEATURE_DEFAULTS } from './contracts.js';
+function skippedReport(now) {
+    return {
+        startedAt: now.toISOString(),
+        completedAt: now.toISOString(),
+        stages: [
+            { stage: 'light', status: 'skipped', processed: 0 },
+            { stage: 'rem', status: 'skipped', processed: 0 },
+            { stage: 'deep', status: 'skipped', processed: 0 },
+        ],
+    };
+}
+/** Generic feature-gated memory runtime; all identity and persistence remain in host adapters. */
+export class AgentMemoryRuntime {
+    options;
+    features;
+    lastDreamingAt = null;
+    lastFailureCode = null;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.features = Object.freeze({ ...MEMORY_FEATURE_DEFAULTS, ...options.features });
+        this.now = options.now ?? (() => new Date());
+    }
+    get autoLearnEnabled() {
+        return this.features.autoLearn;
+    }
+    async observe(authorization, observation) {
+        if (!this.features.autoLearn || !this.options.adapters.observe)
+            return;
+        await this.options.adapters.observe(authorization, observation);
+    }
+    async recall(authorization, request) {
+        if (!this.features.read) {
+            return { mode: 'disabled', reason: 'disabled_by_operator', candidates: [], context: null };
+        }
+        if (!this.options.adapters.recall) {
+            return {
+                mode: 'disabled',
+                reason: 'memory_store_unavailable',
+                candidates: [],
+                context: null,
+            };
+        }
+        return this.options.adapters.recall.recall(authorization, request);
+    }
+    async remember(authorization, write) {
+        if (!this.features.write || !this.options.adapters.writes)
+            return { status: 'not_found' };
+        return this.options.adapters.writes.remember(authorization, write);
+    }
+    async forget(authorization, request) {
+        if (!this.features.write || !this.options.adapters.writes)
+            return { status: 'not_found' };
+        return this.options.adapters.writes.forget(authorization, request);
+    }
+    async recordUsed(authorization, query, candidates) {
+        if (!this.features.read || !this.options.adapters.recall || !candidates.length)
+            return;
+        await this.options.adapters.recall.recordUsed(authorization, query, candidates);
+    }
+    async runDreaming(signal) {
+        if (!this.features.autoLearn)
+            return skippedReport(this.now());
+        if (!this.options.adapters.runDreaming)
+            throw new Error('memory_dreaming_adapter_unavailable');
+        try {
+            const report = await this.options.adapters.runDreaming(signal ?? new AbortController().signal);
+            this.lastDreamingAt = report.completedAt;
+            this.lastFailureCode = null;
+            return report;
+        }
+        catch {
+            this.lastFailureCode = 'dreaming_run_failed';
+            throw new Error('memory_dreaming_run_failed');
+        }
+    }
+    async health() {
+        const missingAdapter = (this.features.read && !this.options.adapters.recall) ||
+            (this.features.write && !this.options.adapters.writes) ||
+            (this.features.autoLearn &&
+                (!this.options.adapters.observe || !this.options.adapters.runDreaming));
+        const reason = this.lastFailureCode ?? (missingAdapter ? 'memory_adapter_unavailable' : null);
+        return { status: reason ? 'degraded' : 'ready', lastDreamingAt: this.lastDreamingAt, reason };
+    }
+}

package/dist/signals.d.ts

@@ -0,0 +1,9 @@
+import type { MemoryUsageSignal } from './contracts.js';
+export interface MemoryUsageCandidate {
+    key: string;
+    revision: number;
+    sourceEventId: string;
+}
+/** Hash a normalized query so recall analytics never retain the query text. */
+export declare function memoryQueryFingerprint(query: string): string;
+export declare function createMemoryUsageSignals(query: string, candidates: readonly MemoryUsageCandidate[]): MemoryUsageSignal[];

package/dist/signals.js

@@ -0,0 +1,37 @@
+import { createHash } from 'node:crypto';
+const MAX_FINGERPRINT_QUERY_LENGTH = 8_000;
+/** Hash a normalized query so recall analytics never retain the query text. */
+export function memoryQueryFingerprint(query) {
+    if (typeof query !== 'string' || query.length > MAX_FINGERPRINT_QUERY_LENGTH) {
+        throw new Error('memory_query_fingerprint_input_invalid');
+    }
+    const normalized = query.normalize('NFKC').trim().replace(/\s+/gu, ' ').toLowerCase();
+    if (!normalized)
+        throw new Error('memory_query_fingerprint_input_invalid');
+    return createHash('sha256').update(normalized, 'utf8').digest('hex');
+}
+export function createMemoryUsageSignals(query, candidates) {
+    const queryFingerprint = memoryQueryFingerprint(query);
+    const unique = new Map();
+    for (const candidate of candidates) {
+        if (!candidate ||
+            typeof candidate.key !== 'string' ||
+            !candidate.key.trim() ||
+            candidate.key.length > 96 ||
+            !Number.isSafeInteger(candidate.revision) ||
+            candidate.revision < 1 ||
+            typeof candidate.sourceEventId !== 'string' ||
+            !candidate.sourceEventId.trim() ||
+            candidate.sourceEventId.length > 256) {
+            continue;
+        }
+        const signal = {
+            key: candidate.key,
+            revision: candidate.revision,
+            sourceEventId: candidate.sourceEventId,
+            queryFingerprint,
+        };
+        unique.set(JSON.stringify([signal.key, signal.revision, signal.sourceEventId]), signal);
+    }
+    return [...unique.values()];
+}

package/dist/write/conflicts.d.ts

@@ -0,0 +1,9 @@
+import type { MemoryEntry } from '../contracts.js';
+export interface MemoryConflictCandidate {
+    entry: MemoryEntry;
+    overlap: number;
+}
+export declare function memoryTokenOverlap(left: string, right: string): number;
+/** Finds likely same-fact conflicts while excluding revisions of the requested key. */
+export declare function findMemoryConflicts(key: string, content: string, entries: readonly MemoryEntry[], minimumOverlap?: number): MemoryConflictCandidate[];
+export declare function equivalentMemoryContent(left: string, right: string, minimumOverlap?: number): boolean;

package/dist/write/conflicts.js

@@ -0,0 +1,38 @@
+import { memorySearchTokens, normalizeMemoryKey } from '../recall/search.js';
+export function memoryTokenOverlap(left, right) {
+    const leftTokens = new Set(memorySearchTokens(left));
+    const rightTokens = new Set(memorySearchTokens(right));
+    if (!leftTokens.size || !rightTokens.size)
+        return 0;
+    let intersection = 0;
+    for (const token of leftTokens)
+        if (rightTokens.has(token))
+            intersection += 1;
+    return intersection / (leftTokens.size + rightTokens.size - intersection);
+}
+/** Finds likely same-fact conflicts while excluding revisions of the requested key. */
+export function findMemoryConflicts(key, content, entries, minimumOverlap = 0.72) {
+    if (!Number.isFinite(minimumOverlap) || minimumOverlap < 0 || minimumOverlap > 1) {
+        throw new Error('memory_conflict_threshold_invalid');
+    }
+    const normalizedKey = normalizeMemoryKey(key);
+    const unique = new Map();
+    for (const entry of entries) {
+        if (!entry || !Number.isSafeInteger(entry.revision) || entry.revision < 1)
+            continue;
+        const candidateKey = normalizeMemoryKey(entry.key);
+        if (!candidateKey || candidateKey === normalizedKey)
+            continue;
+        unique.set(`${candidateKey}\0${entry.revision}`, entry);
+    }
+    return [...unique.values()]
+        .map((entry) => ({
+        entry,
+        overlap: memoryTokenOverlap(`${key} ${content}`, `${entry.key} ${entry.content}`),
+    }))
+        .filter((candidate) => candidate.overlap >= minimumOverlap)
+        .sort((left, right) => right.overlap - left.overlap || left.entry.key.localeCompare(right.entry.key));
+}
+export function equivalentMemoryContent(left, right, minimumOverlap = 0.9) {
+    return memoryTokenOverlap(left, right) >= minimumOverlap;
+}

package/dist/write/service.d.ts

@@ -0,0 +1,18 @@
+import type { ExplicitMemoryWrite, MemoryDraft, MemoryForgetRequest, MemoryWriteMetadata, MemoryWriteResult, MemoryWriteState } from '../contracts.js';
+export interface MemoryWriteStoragePort<TAuthorization> {
+    getWriteState(authorization: TAuthorization, key: string): Promise<MemoryWriteState | null>;
+    create(authorization: TAuthorization, draft: MemoryDraft, metadata: MemoryWriteMetadata): Promise<'created' | 'already_exists'>;
+    revise(authorization: TAuthorization, draft: MemoryDraft, expectedRevision: number, metadata: MemoryWriteMetadata): Promise<boolean>;
+    rememberAgain(authorization: TAuthorization, draft: MemoryDraft, expectedRevision: number, metadata: MemoryWriteMetadata): Promise<boolean>;
+    forget(authorization: TAuthorization, key: string, expectedRevision: number): Promise<boolean>;
+}
+export interface MemoryWriteContext {
+    sourceEventId: string;
+}
+/** Generic explicit write lifecycle; the host port enforces its identity and storage fences. */
+export declare class MemoryWriteService<TAuthorization> {
+    private readonly storage;
+    constructor(storage: MemoryWriteStoragePort<TAuthorization>);
+    remember(authorization: TAuthorization, write: ExplicitMemoryWrite, context: MemoryWriteContext, metadata?: MemoryWriteMetadata): Promise<MemoryWriteResult>;
+    forget(authorization: TAuthorization, request: MemoryForgetRequest, context: MemoryWriteContext): Promise<MemoryWriteResult>;
+}

package/dist/write/service.js

@@ -0,0 +1,85 @@
+import { canonicalizeMemoryKey, validateMemoryDraft } from '../recall/search.js';
+function normalizeMetadata(input) {
+    const sourceKind = input.sourceKind ?? 'user_confirmed';
+    if (!['trusted_ingress', 'user_confirmed', 'system_verified', 'unknown'].includes(sourceKind)) {
+        throw new Error('memory_source_kind_invalid');
+    }
+    const sourceReliability = input.sourceReliability ?? (sourceKind === 'user_confirmed' ? 95 : 80);
+    if (!Number.isSafeInteger(sourceReliability) ||
+        sourceReliability < 0 ||
+        sourceReliability > 100) {
+        throw new Error('memory_source_reliability_invalid');
+    }
+    let validUntil = null;
+    if (input.validUntil != null) {
+        const timestamp = Date.parse(input.validUntil);
+        if (!Number.isFinite(timestamp))
+            throw new Error('memory_valid_until_invalid');
+        validUntil = new Date(timestamp).toISOString();
+    }
+    return { sourceKind, sourceReliability, validUntil };
+}
+function validContext(context) {
+    return (typeof context.sourceEventId === 'string' &&
+        context.sourceEventId.trim().length > 0 &&
+        context.sourceEventId.length <= 256);
+}
+/** Generic explicit write lifecycle; the host port enforces its identity and storage fences. */
+export class MemoryWriteService {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    async remember(authorization, write, context, metadata = {}) {
+        if (!validContext(context))
+            return { status: 'not_found' };
+        const draft = validateMemoryDraft(write);
+        const normalized = normalizeMetadata({
+            sourceKind: 'user_confirmed',
+            sourceReliability: 95,
+            validUntil: write.validUntil ?? null,
+            ...metadata,
+        });
+        const state = await this.storage.getWriteState(authorization, draft.key);
+        if (write.operation === 'correct') {
+            if (!state || state.revoked || write.expectedRevision !== state.revision)
+                return { status: 'not_found' };
+            return (await this.storage.revise(authorization, draft, state.revision, normalized))
+                ? { status: 'revised' }
+                : { status: 'not_found' };
+        }
+        if (state?.revoked) {
+            if (write.expectedRevision !== state.revision)
+                return { status: 'not_found' };
+            return (await this.storage.rememberAgain(authorization, draft, state.revision, normalized))
+                ? { status: 'revised' }
+                : { status: 'not_found' };
+        }
+        if (state)
+            return state.content === draft.content
+                ? { status: 'already_present' }
+                : { status: 'not_found' };
+        if ((await this.storage.create(authorization, draft, normalized)) === 'created')
+            return { status: 'created' };
+        const current = await this.storage.getWriteState(authorization, draft.key);
+        return current &&
+            !current.revoked &&
+            current.sourceEventId === context.sourceEventId &&
+            current.content === draft.content
+            ? { status: 'created' }
+            : { status: 'not_found' };
+    }
+    async forget(authorization, request, context) {
+        if (!validContext(context))
+            return { status: 'not_found' };
+        const key = canonicalizeMemoryKey(request.key);
+        const state = await this.storage.getWriteState(authorization, key);
+        if (!state ||
+            state.revoked ||
+            (request.expectedRevision !== undefined && request.expectedRevision !== state.revision))
+            return { status: 'not_found' };
+        const forgotten = await this.storage.forget(authorization, key, state.revision);
+        const finalState = await this.storage.getWriteState(authorization, key);
+        return forgotten || finalState?.revoked ? { status: 'forgotten' } : { status: 'not_found' };
+    }
+}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@rine-kit/agent-memory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Host-agnostic agent memory runtime: recall (exact/lexical/semantic fusion), explicit writes, evidence-based dreaming. Authorization stays opaque; hosts supply storage, model, embedding and clock ports.",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/ChristmasFox/rine-kit.git",
+    "directory": "packages/agent-memory"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test tests/**/*.test.ts"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.