@mnemonic-ai/core 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/dist/chunk-5Z46NSNR.js +228 -0
  2. package/dist/chunk-5Z46NSNR.js.map +1 -0
  3. package/dist/chunk-CZDK53NR.js +24 -0
  4. package/dist/chunk-CZDK53NR.js.map +1 -0
  5. package/dist/chunk-L7SCUMC3.js +53 -0
  6. package/dist/chunk-L7SCUMC3.js.map +1 -0
  7. package/dist/chunk-M3IZJTMM.js +474 -0
  8. package/dist/chunk-M3IZJTMM.js.map +1 -0
  9. package/dist/chunk-NA7L5FQN.js +1581 -0
  10. package/dist/chunk-NA7L5FQN.js.map +1 -0
  11. package/dist/chunk-OEEEWS2M.js +375 -0
  12. package/dist/chunk-OEEEWS2M.js.map +1 -0
  13. package/dist/chunk-YZW6DYUY.js +46 -0
  14. package/dist/chunk-YZW6DYUY.js.map +1 -0
  15. package/dist/cli/main.cjs +1827 -0
  16. package/dist/cli/main.cjs.map +1 -0
  17. package/dist/cli/main.d.cts +1 -0
  18. package/dist/cli/main.d.ts +1 -0
  19. package/dist/cli/main.js +84 -0
  20. package/dist/cli/main.js.map +1 -0
  21. package/dist/client-b2Xhkqdl.d.cts +409 -0
  22. package/dist/client-b2Xhkqdl.d.ts +409 -0
  23. package/dist/index.cjs +2547 -0
  24. package/dist/index.cjs.map +1 -0
  25. package/dist/index.d.cts +309 -0
  26. package/dist/index.d.ts +309 -0
  27. package/dist/index.js +160 -0
  28. package/dist/index.js.map +1 -0
  29. package/dist/local-MYLINANE.js +7 -0
  30. package/dist/local-MYLINANE.js.map +1 -0
  31. package/dist/mcp/main.cjs +2775 -0
  32. package/dist/mcp/main.cjs.map +1 -0
  33. package/dist/mcp/main.d.cts +1 -0
  34. package/dist/mcp/main.d.ts +1 -0
  35. package/dist/mcp/main.js +31 -0
  36. package/dist/mcp/main.js.map +1 -0
  37. package/dist/mcp/server.cjs +2765 -0
  38. package/dist/mcp/server.cjs.map +1 -0
  39. package/dist/mcp/server.d.cts +23 -0
  40. package/dist/mcp/server.d.ts +23 -0
  41. package/dist/mcp/server.js +12 -0
  42. package/dist/mcp/server.js.map +1 -0
  43. package/dist/openai-GDIC3YVT.js +7 -0
  44. package/dist/openai-GDIC3YVT.js.map +1 -0
  45. package/dist/postgres-GQ6DZDBW.js +8 -0
  46. package/dist/postgres-GQ6DZDBW.js.map +1 -0
  47. package/package.json +117 -0
@@ -0,0 +1,309 @@
1
+ import { B as BaseStore, A as AsyncBaseStore, a as Memory, b as AgentFilterOptions, c as MemoryEdge, S as SimilarPair, d as BaseEmbedder, e as MnemonicConfig, f as SalienceConfig, M as Mnemonic } from './client-b2Xhkqdl.cjs';
2
+ export { g as AddOptions, h as AssemblerConfig, i as BUILTIN_SALIENCE_SIGNALS, j as BUILTIN_TIERS, C as ClassifierConfig, k as ConsolidationConfig, F as ForgetOptions, L as LinkerConfig, l as MemoryInit, m as MemoryTier, P as PromotionConfig, R as RecallOptions, n as SalienceSignal, o as ScorerConfig, p as SortOrder, q as StatsResult, r as StoreFactory, T as TierDefinition, s as createEdge, t as registerStore } from './client-b2Xhkqdl.cjs';
3
+
4
+ /**
5
+ * Adapter that wraps a synchronous BaseStore into an AsyncBaseStore.
6
+ * Uses async functions so thrown errors become rejected promises.
7
+ */
8
+
9
+ /** Wrap a synchronous BaseStore so it can be used as AsyncBaseStore. */
10
+ declare function syncToAsync(store: BaseStore): AsyncBaseStore;
11
+
12
+ /**
13
+ * SQLite-backed memory store — the zero-config default.
14
+ */
15
+
16
+ declare class SQLiteStore implements BaseStore {
17
+ private _db;
18
+ constructor(path?: string);
19
+ initialize(): void;
20
+ close(): void;
21
+ /** Add missing columns/tables for stores created before multi-agent support. */
22
+ private _migrate;
23
+ save(memory: Memory): void;
24
+ get(memoryId: string): Memory | null;
25
+ listAll(options?: AgentFilterOptions): Memory[];
26
+ delete(memoryId: string): void;
27
+ deleteOlderThan(ageMs: number, tier?: string, options?: AgentFilterOptions): number;
28
+ saveEdge(edge: MemoryEdge): void;
29
+ getEdges(memoryId: string): MemoryEdge[];
30
+ searchByEmbedding(embedding: number[], limit?: number, options?: AgentFilterOptions): Memory[];
31
+ findSimilarPairs(options?: {
32
+ threshold?: number;
33
+ agentId?: string;
34
+ tier?: string;
35
+ maxCandidates?: number;
36
+ maxNeighborsPerCandidate?: number;
37
+ }): SimilarPair[];
38
+ getMeta(key: string): string | null;
39
+ setMeta(key: string, value: string): void;
40
+ }
41
+
42
+ /**
43
+ * PostgreSQL + pgvector memory store — production-grade async backend.
44
+ */
45
+
46
+ interface PostgresStoreOptions {
47
+ /** PostgreSQL connection string (e.g. postgresql://user:pass@host:5432/db). */
48
+ dsn: string;
49
+ /** Embedding vector dimension (default 1536). */
50
+ embeddingDim?: number;
51
+ /** Minimum pool connections (default 2). */
52
+ poolMin?: number;
53
+ /** Maximum pool connections (default 10). */
54
+ poolMax?: number;
55
+ }
56
+ declare class PostgresStore implements AsyncBaseStore {
57
+ private _dsn;
58
+ private _embeddingDim;
59
+ private _poolMin;
60
+ private _poolMax;
61
+ private _pool;
62
+ private _pgvectorRegistered;
63
+ constructor(options: PostgresStoreOptions);
64
+ private _getPool;
65
+ private _query;
66
+ /** Register pgvector on the pool's connect event so every connection gets it. */
67
+ private _setupPgvectorOnPool;
68
+ initialize(): Promise<void>;
69
+ private _migrateColumns;
70
+ close(): Promise<void>;
71
+ save(memory: Memory): Promise<void>;
72
+ get(memoryId: string): Promise<Memory | null>;
73
+ listAll(options?: AgentFilterOptions): Promise<Memory[]>;
74
+ delete(memoryId: string): Promise<void>;
75
+ deleteOlderThan(ageMs: number, tier?: string, options?: AgentFilterOptions): Promise<number>;
76
+ saveEdge(edge: MemoryEdge): Promise<void>;
77
+ getEdges(memoryId: string): Promise<MemoryEdge[]>;
78
+ searchByEmbedding(embedding: number[], limit?: number, options?: AgentFilterOptions): Promise<Memory[]>;
79
+ findSimilarPairs(options?: {
80
+ threshold?: number;
81
+ agentId?: string;
82
+ tier?: string;
83
+ maxCandidates?: number;
84
+ maxNeighborsPerCandidate?: number;
85
+ }): Promise<SimilarPair[]>;
86
+ getMeta(key: string): Promise<string | null>;
87
+ setMeta(key: string, value: string): Promise<void>;
88
+ }
89
+
90
+ /**
91
+ * OpenAI embedding provider.
92
+ *
93
+ * Requires the `openai` package as a peer dependency.
94
+ */
95
+
96
+ declare class OpenAIEmbedder implements BaseEmbedder {
97
+ private _model;
98
+ private _apiKey;
99
+ private _client;
100
+ constructor(options?: {
101
+ model?: string;
102
+ apiKey?: string;
103
+ });
104
+ get dimension(): number;
105
+ private getClient;
106
+ embed(text: string): Promise<number[]>;
107
+ embedBatch(texts: string[]): Promise<number[][]>;
108
+ }
109
+
110
+ /**
111
+ * Local embedder using @huggingface/transformers (ONNX runtime).
112
+ * Default model: Xenova/all-MiniLM-L6-v2 (384 dimensions).
113
+ */
114
+
115
+ interface LocalEmbedderOptions {
116
+ /** HuggingFace model name (default: "Xenova/all-MiniLM-L6-v2"). */
117
+ model?: string;
118
+ }
119
+ declare class LocalEmbedder implements BaseEmbedder {
120
+ private _modelName;
121
+ private _pipeline;
122
+ private _dimension;
123
+ constructor(options?: LocalEmbedderOptions);
124
+ get dimension(): number;
125
+ private _getPipeline;
126
+ embed(text: string): Promise<number[]>;
127
+ embedBatch(texts: string[]): Promise<number[][]>;
128
+ }
129
+
130
+ /**
131
+ * Embedder factory — resolves MNEMONIC_EMBEDDER env var to a concrete embedder.
132
+ */
133
+
134
+ /**
135
+ * Build an embedder based on provider name (or MNEMONIC_EMBEDDER env var).
136
+ *
137
+ * - "none" → null (keyword-only mode)
138
+ * - "openai" → OpenAIEmbedder
139
+ * - "local" → LocalEmbedder (@huggingface/transformers)
140
+ *
141
+ * Returns null if provider is "none" or empty.
142
+ * Throws if provider is unrecognised.
143
+ */
144
+ declare function buildEmbedder(provider?: string): Promise<BaseEmbedder | null>;
145
+
146
+ /**
147
+ * Tier classifier with configurable patterns and pluggable custom logic.
148
+ */
149
+
150
+ /** Return the most appropriate tier name for the given content. */
151
+ declare function classify(content: string, options?: {
152
+ source?: string;
153
+ actor?: string;
154
+ config?: MnemonicConfig;
155
+ }): string;
156
+
157
+ /**
158
+ * Dynamic importance scoring engine.
159
+ */
160
+
161
+ /** Compute the current importance score for a memory. */
162
+ declare function score(memory: Memory, config?: MnemonicConfig): number;
163
+
164
+ /**
165
+ * Relationship detection between memories.
166
+ */
167
+
168
+ /** Identify edges from newMemory to the most related existing memories. */
169
+ declare function findLinks(newMemory: Memory, existing: Memory[], options?: {
170
+ config?: MnemonicConfig;
171
+ similarityThreshold?: number;
172
+ maxLinks?: number;
173
+ }): MemoryEdge[];
174
+
175
+ /**
176
+ * Context window assembly — greedy budget-filling with diversity penalty.
177
+ *
178
+ * Uses pre-computed similarity matrices for O(1) diversity lookups.
179
+ */
180
+
181
+ /** Select and order memories to fill a token budget. */
182
+ declare function assemble(_query: string, candidates: Memory[], options?: {
183
+ queryEmbedding?: number[] | null;
184
+ maxTokens?: number;
185
+ diversityStrength?: number;
186
+ minRelevance?: number;
187
+ config?: MnemonicConfig;
188
+ }): Memory[];
189
+ /** Render assembled memories as a plain-text block. */
190
+ declare function formatContext(memories: Memory[], header?: string, conflicts?: Array<[number, number, string]>): string;
191
+
192
+ /**
193
+ * Tier promotion and demotion — the memory maturation pipeline.
194
+ *
195
+ * transient → episodic → structural → identity
196
+ * ↑
197
+ * procedural ──┘
198
+ */
199
+
200
+ interface PromotionResult {
201
+ memoryId: string;
202
+ oldTier: string;
203
+ newTier: string;
204
+ reason: string;
205
+ }
206
+ /** Identify memories that qualify for tier promotion. */
207
+ declare function checkPromotions(memories: Memory[], config?: MnemonicConfig): PromotionResult[];
208
+ /** Identify memories that qualify for tier demotion. */
209
+ declare function checkDemotions(memories: Memory[], config?: MnemonicConfig): PromotionResult[];
210
+ /** Change a memory's tier in-place, recording history. */
211
+ declare function applyTierChange(memory: Memory, newTier: string): void;
212
+
213
+ /**
214
+ * Automatic salience detection — the amygdala of the memory system.
215
+ */
216
+
217
+ interface SalienceResult {
218
+ boost: number;
219
+ signals: string[];
220
+ }
221
+ /** Scan content for salience signals. */
222
+ declare function detectSalience(content: string, config?: SalienceConfig): SalienceResult;
223
+
224
+ /**
225
+ * Memory consolidation — merging episodic memories into semantic summaries.
226
+ */
227
+
228
+ /** Error names that indicate transient LLM failures — should propagate, not fall back. */
229
+ declare const TRANSIENT_ERRORS: Set<string>;
230
+ /**
231
+ * Group episodic memories that overlap enough to consolidate.
232
+ *
233
+ * When `pairs` is provided, union-find runs directly on the sparse pairs
234
+ * (no N×N matrix). When omitted, falls back to brute-force matrix.
235
+ */
236
+ declare function findConsolidationCandidates(memories: Memory[], config?: MnemonicConfig, pairs?: SimilarPair[]): Memory[][];
237
+ /** Create a single structural memory summarising a cluster. */
238
+ declare function mergeCluster(cluster: Memory[], config?: MnemonicConfig): Promise<Memory>;
239
+
240
+ /**
241
+ * Raw API adapter — simple helper for injecting memory context into prompts.
242
+ */
243
+
244
+ interface RecallAsPromptOptions {
245
+ maxTokens?: number;
246
+ header?: string;
247
+ }
248
+ /**
249
+ * Retrieve memory context formatted for direct inclusion in a system prompt.
250
+ *
251
+ * ```ts
252
+ * const context = await recallAsPrompt(mem, userQuery);
253
+ * const systemPrompt = `You are helpful.\n\n${context}`;
254
+ * ```
255
+ */
256
+ declare function recallAsPrompt(mnemonic: Mnemonic, query: string, options?: RecallAsPromptOptions): Promise<string>;
257
+
258
+ /**
259
+ * LangChain.js adapter — wraps Mnemonic as a LangChain BaseMemory.
260
+ * Requires @langchain/core as a peer dependency.
261
+ */
262
+
263
+ interface LangChainMemoryOptions {
264
+ /** The Mnemonic client instance. */
265
+ mnemonic: Mnemonic;
266
+ /** Key used in the memory variables dict (default "memory"). */
267
+ memoryKey?: string;
268
+ /** Max tokens for recall (default 3000). */
269
+ maxTokens?: number;
270
+ /** Input key for multi-key chains (auto-detected if single key). */
271
+ inputKey?: string;
272
+ /** Output key for multi-key chains (auto-detected if single key). */
273
+ outputKey?: string;
274
+ }
275
+ /**
276
+ * Create a LangChain-compatible memory wrapper.
277
+ * Must be called with await since it dynamically imports @langchain/core.
278
+ *
279
+ * ```ts
280
+ * const memory = await createLangChainMemory({ mnemonic: client });
281
+ * const chain = new ConversationChain({ memory });
282
+ * ```
283
+ */
284
+ declare function createLangChainMemory(options: LangChainMemoryOptions): Promise<any>;
285
+
286
+ /**
287
+ * Shared utility functions.
288
+ */
289
+
290
+ /** Cosine similarity between two vectors. Returns 0 if either is zero-norm. */
291
+ declare function cosineSimilarity(a: number[], b: number[]): number;
292
+ /**
293
+ * Cosine similarity between a single query and a list of embeddings.
294
+ * Returns an array of similarities, one per embedding.
295
+ */
296
+ declare function cosineSimilarityVector(query: number[], embeddings: number[][]): Float64Array;
297
+ /**
298
+ * Pairwise cosine similarity matrix for a list of embeddings.
299
+ * Returns a flat Float64Array of size n*n (row-major).
300
+ */
301
+ declare function cosineSimilarityMatrix(embeddings: number[][]): Float64Array;
302
+ /** Parse human-friendly durations like '30d', '24h', '90m', '2w', '120s'. Returns milliseconds. */
303
+ declare function parseDuration(s: string): number;
304
+ /** Rough token count estimate. */
305
+ declare function estimateTokens(text: string, charsPerToken?: number): number;
306
+ /** Rank memories by cosine similarity to embedding, return top limit. */
307
+ declare function bruteForceCosineSearch(memories: Memory[], embedding: number[], limit: number): Memory[];
308
+
309
+ export { AgentFilterOptions, AsyncBaseStore, BaseEmbedder, BaseStore, type LangChainMemoryOptions, LocalEmbedder, type LocalEmbedderOptions, Memory, MemoryEdge, Mnemonic, MnemonicConfig, OpenAIEmbedder, PostgresStore, type PostgresStoreOptions, type PromotionResult, type RecallAsPromptOptions, SQLiteStore, SalienceConfig, type SalienceResult, SimilarPair, TRANSIENT_ERRORS, applyTierChange, assemble, bruteForceCosineSearch, buildEmbedder, checkDemotions, checkPromotions, classify, cosineSimilarity, cosineSimilarityMatrix, cosineSimilarityVector, createLangChainMemory, detectSalience, estimateTokens, findConsolidationCandidates, findLinks, formatContext, mergeCluster, parseDuration, recallAsPrompt, score, syncToAsync };
@@ -0,0 +1,309 @@
1
+ import { B as BaseStore, A as AsyncBaseStore, a as Memory, b as AgentFilterOptions, c as MemoryEdge, S as SimilarPair, d as BaseEmbedder, e as MnemonicConfig, f as SalienceConfig, M as Mnemonic } from './client-b2Xhkqdl.js';
2
+ export { g as AddOptions, h as AssemblerConfig, i as BUILTIN_SALIENCE_SIGNALS, j as BUILTIN_TIERS, C as ClassifierConfig, k as ConsolidationConfig, F as ForgetOptions, L as LinkerConfig, l as MemoryInit, m as MemoryTier, P as PromotionConfig, R as RecallOptions, n as SalienceSignal, o as ScorerConfig, p as SortOrder, q as StatsResult, r as StoreFactory, T as TierDefinition, s as createEdge, t as registerStore } from './client-b2Xhkqdl.js';
3
+
4
+ /**
5
+ * Adapter that wraps a synchronous BaseStore into an AsyncBaseStore.
6
+ * Uses async functions so thrown errors become rejected promises.
7
+ */
8
+
9
+ /** Wrap a synchronous BaseStore so it can be used as AsyncBaseStore. */
10
+ declare function syncToAsync(store: BaseStore): AsyncBaseStore;
11
+
12
+ /**
13
+ * SQLite-backed memory store — the zero-config default.
14
+ */
15
+
16
+ declare class SQLiteStore implements BaseStore {
17
+ private _db;
18
+ constructor(path?: string);
19
+ initialize(): void;
20
+ close(): void;
21
+ /** Add missing columns/tables for stores created before multi-agent support. */
22
+ private _migrate;
23
+ save(memory: Memory): void;
24
+ get(memoryId: string): Memory | null;
25
+ listAll(options?: AgentFilterOptions): Memory[];
26
+ delete(memoryId: string): void;
27
+ deleteOlderThan(ageMs: number, tier?: string, options?: AgentFilterOptions): number;
28
+ saveEdge(edge: MemoryEdge): void;
29
+ getEdges(memoryId: string): MemoryEdge[];
30
+ searchByEmbedding(embedding: number[], limit?: number, options?: AgentFilterOptions): Memory[];
31
+ findSimilarPairs(options?: {
32
+ threshold?: number;
33
+ agentId?: string;
34
+ tier?: string;
35
+ maxCandidates?: number;
36
+ maxNeighborsPerCandidate?: number;
37
+ }): SimilarPair[];
38
+ getMeta(key: string): string | null;
39
+ setMeta(key: string, value: string): void;
40
+ }
41
+
42
+ /**
43
+ * PostgreSQL + pgvector memory store — production-grade async backend.
44
+ */
45
+
46
+ interface PostgresStoreOptions {
47
+ /** PostgreSQL connection string (e.g. postgresql://user:pass@host:5432/db). */
48
+ dsn: string;
49
+ /** Embedding vector dimension (default 1536). */
50
+ embeddingDim?: number;
51
+ /** Minimum pool connections (default 2). */
52
+ poolMin?: number;
53
+ /** Maximum pool connections (default 10). */
54
+ poolMax?: number;
55
+ }
56
+ declare class PostgresStore implements AsyncBaseStore {
57
+ private _dsn;
58
+ private _embeddingDim;
59
+ private _poolMin;
60
+ private _poolMax;
61
+ private _pool;
62
+ private _pgvectorRegistered;
63
+ constructor(options: PostgresStoreOptions);
64
+ private _getPool;
65
+ private _query;
66
+ /** Register pgvector on the pool's connect event so every connection gets it. */
67
+ private _setupPgvectorOnPool;
68
+ initialize(): Promise<void>;
69
+ private _migrateColumns;
70
+ close(): Promise<void>;
71
+ save(memory: Memory): Promise<void>;
72
+ get(memoryId: string): Promise<Memory | null>;
73
+ listAll(options?: AgentFilterOptions): Promise<Memory[]>;
74
+ delete(memoryId: string): Promise<void>;
75
+ deleteOlderThan(ageMs: number, tier?: string, options?: AgentFilterOptions): Promise<number>;
76
+ saveEdge(edge: MemoryEdge): Promise<void>;
77
+ getEdges(memoryId: string): Promise<MemoryEdge[]>;
78
+ searchByEmbedding(embedding: number[], limit?: number, options?: AgentFilterOptions): Promise<Memory[]>;
79
+ findSimilarPairs(options?: {
80
+ threshold?: number;
81
+ agentId?: string;
82
+ tier?: string;
83
+ maxCandidates?: number;
84
+ maxNeighborsPerCandidate?: number;
85
+ }): Promise<SimilarPair[]>;
86
+ getMeta(key: string): Promise<string | null>;
87
+ setMeta(key: string, value: string): Promise<void>;
88
+ }
89
+
90
+ /**
91
+ * OpenAI embedding provider.
92
+ *
93
+ * Requires the `openai` package as a peer dependency.
94
+ */
95
+
96
+ declare class OpenAIEmbedder implements BaseEmbedder {
97
+ private _model;
98
+ private _apiKey;
99
+ private _client;
100
+ constructor(options?: {
101
+ model?: string;
102
+ apiKey?: string;
103
+ });
104
+ get dimension(): number;
105
+ private getClient;
106
+ embed(text: string): Promise<number[]>;
107
+ embedBatch(texts: string[]): Promise<number[][]>;
108
+ }
109
+
110
+ /**
111
+ * Local embedder using @huggingface/transformers (ONNX runtime).
112
+ * Default model: Xenova/all-MiniLM-L6-v2 (384 dimensions).
113
+ */
114
+
115
+ interface LocalEmbedderOptions {
116
+ /** HuggingFace model name (default: "Xenova/all-MiniLM-L6-v2"). */
117
+ model?: string;
118
+ }
119
+ declare class LocalEmbedder implements BaseEmbedder {
120
+ private _modelName;
121
+ private _pipeline;
122
+ private _dimension;
123
+ constructor(options?: LocalEmbedderOptions);
124
+ get dimension(): number;
125
+ private _getPipeline;
126
+ embed(text: string): Promise<number[]>;
127
+ embedBatch(texts: string[]): Promise<number[][]>;
128
+ }
129
+
130
+ /**
131
+ * Embedder factory — resolves MNEMONIC_EMBEDDER env var to a concrete embedder.
132
+ */
133
+
134
+ /**
135
+ * Build an embedder based on provider name (or MNEMONIC_EMBEDDER env var).
136
+ *
137
+ * - "none" → null (keyword-only mode)
138
+ * - "openai" → OpenAIEmbedder
139
+ * - "local" → LocalEmbedder (@huggingface/transformers)
140
+ *
141
+ * Returns null if provider is "none" or empty.
142
+ * Throws if provider is unrecognised.
143
+ */
144
+ declare function buildEmbedder(provider?: string): Promise<BaseEmbedder | null>;
145
+
146
+ /**
147
+ * Tier classifier with configurable patterns and pluggable custom logic.
148
+ */
149
+
150
+ /** Return the most appropriate tier name for the given content. */
151
+ declare function classify(content: string, options?: {
152
+ source?: string;
153
+ actor?: string;
154
+ config?: MnemonicConfig;
155
+ }): string;
156
+
157
+ /**
158
+ * Dynamic importance scoring engine.
159
+ */
160
+
161
+ /** Compute the current importance score for a memory. */
162
+ declare function score(memory: Memory, config?: MnemonicConfig): number;
163
+
164
+ /**
165
+ * Relationship detection between memories.
166
+ */
167
+
168
+ /** Identify edges from newMemory to the most related existing memories. */
169
+ declare function findLinks(newMemory: Memory, existing: Memory[], options?: {
170
+ config?: MnemonicConfig;
171
+ similarityThreshold?: number;
172
+ maxLinks?: number;
173
+ }): MemoryEdge[];
174
+
175
+ /**
176
+ * Context window assembly — greedy budget-filling with diversity penalty.
177
+ *
178
+ * Uses pre-computed similarity matrices for O(1) diversity lookups.
179
+ */
180
+
181
+ /** Select and order memories to fill a token budget. */
182
+ declare function assemble(_query: string, candidates: Memory[], options?: {
183
+ queryEmbedding?: number[] | null;
184
+ maxTokens?: number;
185
+ diversityStrength?: number;
186
+ minRelevance?: number;
187
+ config?: MnemonicConfig;
188
+ }): Memory[];
189
+ /** Render assembled memories as a plain-text block. */
190
+ declare function formatContext(memories: Memory[], header?: string, conflicts?: Array<[number, number, string]>): string;
191
+
192
+ /**
193
+ * Tier promotion and demotion — the memory maturation pipeline.
194
+ *
195
+ * transient → episodic → structural → identity
196
+ * ↑
197
+ * procedural ──┘
198
+ */
199
+
200
+ interface PromotionResult {
201
+ memoryId: string;
202
+ oldTier: string;
203
+ newTier: string;
204
+ reason: string;
205
+ }
206
+ /** Identify memories that qualify for tier promotion. */
207
+ declare function checkPromotions(memories: Memory[], config?: MnemonicConfig): PromotionResult[];
208
+ /** Identify memories that qualify for tier demotion. */
209
+ declare function checkDemotions(memories: Memory[], config?: MnemonicConfig): PromotionResult[];
210
+ /** Change a memory's tier in-place, recording history. */
211
+ declare function applyTierChange(memory: Memory, newTier: string): void;
212
+
213
+ /**
214
+ * Automatic salience detection — the amygdala of the memory system.
215
+ */
216
+
217
+ interface SalienceResult {
218
+ boost: number;
219
+ signals: string[];
220
+ }
221
+ /** Scan content for salience signals. */
222
+ declare function detectSalience(content: string, config?: SalienceConfig): SalienceResult;
223
+
224
+ /**
225
+ * Memory consolidation — merging episodic memories into semantic summaries.
226
+ */
227
+
228
+ /** Error names that indicate transient LLM failures — should propagate, not fall back. */
229
+ declare const TRANSIENT_ERRORS: Set<string>;
230
+ /**
231
+ * Group episodic memories that overlap enough to consolidate.
232
+ *
233
+ * When `pairs` is provided, union-find runs directly on the sparse pairs
234
+ * (no N×N matrix). When omitted, falls back to brute-force matrix.
235
+ */
236
+ declare function findConsolidationCandidates(memories: Memory[], config?: MnemonicConfig, pairs?: SimilarPair[]): Memory[][];
237
+ /** Create a single structural memory summarising a cluster. */
238
+ declare function mergeCluster(cluster: Memory[], config?: MnemonicConfig): Promise<Memory>;
239
+
240
+ /**
241
+ * Raw API adapter — simple helper for injecting memory context into prompts.
242
+ */
243
+
244
+ interface RecallAsPromptOptions {
245
+ maxTokens?: number;
246
+ header?: string;
247
+ }
248
+ /**
249
+ * Retrieve memory context formatted for direct inclusion in a system prompt.
250
+ *
251
+ * ```ts
252
+ * const context = await recallAsPrompt(mem, userQuery);
253
+ * const systemPrompt = `You are helpful.\n\n${context}`;
254
+ * ```
255
+ */
256
+ declare function recallAsPrompt(mnemonic: Mnemonic, query: string, options?: RecallAsPromptOptions): Promise<string>;
257
+
258
+ /**
259
+ * LangChain.js adapter — wraps Mnemonic as a LangChain BaseMemory.
260
+ * Requires @langchain/core as a peer dependency.
261
+ */
262
+
263
+ interface LangChainMemoryOptions {
264
+ /** The Mnemonic client instance. */
265
+ mnemonic: Mnemonic;
266
+ /** Key used in the memory variables dict (default "memory"). */
267
+ memoryKey?: string;
268
+ /** Max tokens for recall (default 3000). */
269
+ maxTokens?: number;
270
+ /** Input key for multi-key chains (auto-detected if single key). */
271
+ inputKey?: string;
272
+ /** Output key for multi-key chains (auto-detected if single key). */
273
+ outputKey?: string;
274
+ }
275
+ /**
276
+ * Create a LangChain-compatible memory wrapper.
277
+ * Must be called with await since it dynamically imports @langchain/core.
278
+ *
279
+ * ```ts
280
+ * const memory = await createLangChainMemory({ mnemonic: client });
281
+ * const chain = new ConversationChain({ memory });
282
+ * ```
283
+ */
284
+ declare function createLangChainMemory(options: LangChainMemoryOptions): Promise<any>;
285
+
286
+ /**
287
+ * Shared utility functions.
288
+ */
289
+
290
+ /** Cosine similarity between two vectors. Returns 0 if either is zero-norm. */
291
+ declare function cosineSimilarity(a: number[], b: number[]): number;
292
+ /**
293
+ * Cosine similarity between a single query and a list of embeddings.
294
+ * Returns an array of similarities, one per embedding.
295
+ */
296
+ declare function cosineSimilarityVector(query: number[], embeddings: number[][]): Float64Array;
297
+ /**
298
+ * Pairwise cosine similarity matrix for a list of embeddings.
299
+ * Returns a flat Float64Array of size n*n (row-major).
300
+ */
301
+ declare function cosineSimilarityMatrix(embeddings: number[][]): Float64Array;
302
+ /** Parse human-friendly durations like '30d', '24h', '90m', '2w', '120s'. Returns milliseconds. */
303
+ declare function parseDuration(s: string): number;
304
+ /** Rough token count estimate. */
305
+ declare function estimateTokens(text: string, charsPerToken?: number): number;
306
+ /** Rank memories by cosine similarity to embedding, return top limit. */
307
+ declare function bruteForceCosineSearch(memories: Memory[], embedding: number[], limit: number): Memory[];
308
+
309
+ export { AgentFilterOptions, AsyncBaseStore, BaseEmbedder, BaseStore, type LangChainMemoryOptions, LocalEmbedder, type LocalEmbedderOptions, Memory, MemoryEdge, Mnemonic, MnemonicConfig, OpenAIEmbedder, PostgresStore, type PostgresStoreOptions, type PromotionResult, type RecallAsPromptOptions, SQLiteStore, SalienceConfig, type SalienceResult, SimilarPair, TRANSIENT_ERRORS, applyTierChange, assemble, bruteForceCosineSearch, buildEmbedder, checkDemotions, checkPromotions, classify, cosineSimilarity, cosineSimilarityMatrix, cosineSimilarityVector, createLangChainMemory, detectSalience, estimateTokens, findConsolidationCandidates, findLinks, formatContext, mergeCluster, parseDuration, recallAsPrompt, score, syncToAsync };