@monoes/memory

@monoes/memory

Persistent memory backends for Monomind agents — SQLite in WAL journal mode (PRAGMA journal_mode = WAL, schema v3.0.0) key-value storage with dense ONNX ModernBERT 768d + Okapi BM25 RRF hybrid search, surface query routing, Open Knowledge Format (OKF) transfer, Cognee-style knowledge graph triplets, and EWC pattern consolidation.

Part of the Monomind ecosystem. The embedded storage layer uses better-sqlite3 with sql.js (WASM zero-compile fallback).

Install

npm install @monoes/memory

better-sqlite3 ships as a direct dependency (native SQLite; sql.js WASM is the fallback storage engine) — no separate install needed.

Native module install blocked? If initialization throws Could not locate the bindings file, your npm's allowScripts policy blocked better-sqlite3's native build — run npm install-scripts approve better-sqlite3 && npm rebuild better-sqlite3.

Core Architecture & Schema v3.0.0

Schema Architecture & Storage Engine

• Storage Driver: Operates over SQLite with WAL mode (PRAGMA journal_mode = WAL) using better-sqlite3 with a WASM sql.js fallback.
• Dual Schema Support:
  • Standalone @monoes/memory core schema (packages/@monomind/memory/src/sql-schema.ts:28): SCHEMA_VERSION = 2 managing 4 tables (memory_entries, memory_embeddings, memory_entry_tags, agent_reads).
  • CLI project memory schema (packages/@monomind/cli/src/memory/memory-schema.ts:15): Schema version 3.0.0 managing 9 tables (memory_entries, patterns, pattern_history, trajectories, trajectory_steps, migration_state, sessions, vector_indexes, metadata).

Hybrid Search: ONNX ModernBERT 768d + BM25 RRF

Retrieval uses a dual-arm hybrid search architecture combined with Reciprocal Rank Fusion (RRF):

• Dense Vector Search:
  • Model: Alibaba-NLP/gte-modernbert-base (768 dimensions).
  • Embedding Pipeline: @xenova/transformers ONNX feature extraction.
  • Acceleration: Standalone pure-JS HNSWIndex (dimensions=768, M=16, efConstruction=200, metric='cosine').
• Lexical Arm (In-Process Okapi BM25):
  • Parameters: $k_1 = 1.2$, $b = 0.75$.
  • Tokenizer: Exact parity with the evaluation harness (text-tokens.ts).
  • Live-Only Indexing: Built dynamically over live chunks with warning thresholds at 50,000 chunks (LIVE_CHUNK_WARN_THRESHOLD) and persistent review at 1,000,000 chunks (SCALING_REVIEW_CHUNKS).
• Reciprocal Rank Fusion (RRF):
  • Fuses ranked candidate lists using adaptive constant $k = \max(30, \min(60, 20 + 2 \times \text{top_k}))$: $$\text{Score}(d) = \sum_{m} \frac{1}{\text{rrf_k} + \text{rank}_m + 1} \times (0.75 + 0.5 \times \text{importance})$$

Surface Query Router

The QueryRouter (query-router.ts) evaluates queries across 4 target surfaces: chunks (prior 0.5), kg (wt 2), rules (wt 2), and memory (wt 2):

• Negation Gate: Uses a 20-character pre-match window (NEGATION_RE) to bypass negated query phrases.
• Confidence Gate: Requires top surface score $\ge 2 \times$ runner-up score; low-confidence queries query all surfaces and fuse results.
• Telemetry Persistence: Cross-process misroutes are recorded to .monomind/metrics/route-overrides.json.

Open Knowledge Format (OKF) Bundles

Supports document and memory export/import via Open Knowledge Format (OKF) Markdown files with YAML frontmatter headers:

• Document OKF: Exported via exportToOKF() with frontmatter (type: Document, title, description, resource, tags, timestamp, contentHash, chunkCount) and an index.md manifest.
• Memory Transfer OKF: CLI commands monomind memory export and import export/restore key-value memory entries across namespace directory trees.

EWC Pattern Consolidation & SONA Router

• EWC Consolidation (ewc-consolidation.ts): Applies Elastic Weight Consolidation using an EMA-updated Fisher information matrix (computeFisherMatrix) persisted in .swarm/ewc-fisher.json to prevent catastrophic forgetting during pattern updates.
• SONA Router (sona-optimizer.ts): Extracts routing patterns from hooksTrajectoryEnd events into .swarm/sona-patterns.json.

Exported Components

Export	What it does
SQLiteBackend / SqlJsBackend	Structured key-value storage in SQLite WAL mode (native + WASM fallback)
HNSWIndex	Standalone pure-JS approximate nearest-neighbor index (768d)
chunkDocument, KnowledgeStore, KnowledgeRetriever	Document chunking + retrieval pipeline
QueryBuilder / query()	Fluent query construction
CacheManager	In-memory LRU caching with size/TTL limits
SwarmCheckpointer	Persist/restore swarm agent state snapshots
MemoryMigrator	Import from SQLite, JSON, or Markdown sources
PromptVersionStore	Prompt version history & prompt experiment tracking

Cross-Platform Notes

The memory storage engine selects the best available SQLite driver per platform: better-sqlite3 (native, fastest) with automatic fallback to sql.js (WASM, zero compilation, works everywhere including Windows without a toolchain).

Links

• GitHub
• Documentation
• Issues

License

MIT