mnemonic-memory

3-tier AI memory system: hot Redis cache → warm semantic vectors → cold SQLite

Drop-in persistent memory for AI agents, chatbots, and LLM applications. Automatically routes queries to the fastest available tier and falls back gracefully when components aren't available.

Query → Redis (< 1ms) → Vector Search (~10ms) → SQLite LIKE (~50ms)

---

Install

npm install mnemonic-memory

For semantic search (recommended):

npm install @xenova/transformers

For hot-tier caching (optional):

npm install redis

---

Quick start

import { MnemonicMemory } from 'mnemonic-memory';

const mem = new MnemonicMemory({ dbPath: './memory.db' });
await mem.init();

// Store
await mem.remember('Paris is the capital of France', { category: 'geo' });
await mem.remember('Mitochondria are the powerhouse of the cell', { category: 'biology' });

// Recall by meaning (not just keywords)
const { results, tier, latencyMs } = await mem.recall('French capital city');
console.log(results[0].content);  // → "Paris is the capital of France"
console.log(tier);                // → "warm" (vector search)

// Forget
await mem.forget(results[0].id);

await mem.close();

---

How the tiers work

Tier	Storage	Latency	When used
Hot	Redis in-memory	< 1ms	Exact/repeated queries
Warm	In-memory vector index	~10ms	Semantic similarity search
Cold	SQLite on disk	~50ms	Fallback, persistence, recent queries

Tier promotion: Frequently accessed memories bubble up automatically.

• Cold → Warm after 5 accesses
• Warm → Hot after 10 accesses

Tier demotion: Stale memories sink back down.

• Hot → Warm if not accessed in 1 hour
• Warm → Cold if not accessed in 7 days

All three tiers fail gracefully — if Redis isn't running, queries go to vectors. If @xenova/transformers isn't installed, queries go to SQLite LIKE search.

---

API

new MnemonicMemory(opts)

Option	Type	Default	Description
dbPath	string	./mnemonic.db	SQLite file path
vectorPath	string	./mnemonic-vectors.json	Vector store path
redisUrl	string	—	Redis URL. Omit to skip hot tier
embeddingModel	string	Xenova/all-MiniLM-L6-v2	HuggingFace model for embeddings
skipEmbedder	boolean	false	Skip loading model (faster startup)
similarityThreshold	number	0.45	Min cosine similarity (0–1)
hotTTL	number	3600	Redis key TTL in seconds
warmLimit	number	50000	Max vectors in memory
saveIntervalMs	number	120000	Auto-save vectors every N ms
enableAutoCleanup	boolean	true	Prune stale access tracking

mem.init() → Promise<void>

Initialize all tiers. Must be called before any other method.

mem.remember(content, metadata?, importance?) → Promise<{ id, tiers }>

Store a memory. importance is 0.0–1.0 (default 0.5) and affects search ranking.

mem.recall(query, topK?) → Promise<{ results, tier, latencyMs }>

Search memories using the best available tier. results is an array of memory objects, each with id, content, metadata, tier, and optionally similarity.

mem.get(id) → Promise<object|null>

Retrieve a specific memory by ID.

mem.forget(id) → Promise<{ id, forgotten }>

Delete a memory from all tiers.

mem.recent(hours?, limit?) → Promise<Array>

Get memories created within the last N hours.

mem.stats() → object

Per-tier hit rates, sizes, and metrics.

mem.close() → Promise<void>

Persist vectors to disk and close connections.

---

Events

mem.on('ready',               ()            => ...)
mem.on('embedder_ready',      (modelName)   => ...)
mem.on('embedder_unavailable', (reason)     => ...)
mem.on('stored',              ({ id, tiers }) => ...)
mem.on('recalled',            ({ results, tier, latencyMs }) => ...)
mem.on('forgotten',           ({ id })      => ...)
mem.on('closed',              ()            => ...)

---

Without Redis or embeddings

Works fine with no optional dependencies — just SQLite:

const mem = new MnemonicMemory({
  dbPath:       './memory.db',
  skipEmbedder: true,   // No @xenova/transformers needed
  // no redisUrl        // No Redis needed
});
await mem.init();

Queries fall back to SQLite full-text LIKE search. Slower than vector search but zero additional dependencies.

---

License

MIT