@jeremiaheth/neolata-mem 0.5.3 → 0.8.1

package/README.md

@@ -94,7 +94,7 @@ const report = await mem.decay({ dryRun: true });  // Preview what would be prun
 await mem.decay();  // Archive weak memories, delete dead ones
 ```
 
-### ⚔️ Conflict Resolution
+### ⚔️ Conflict Resolution & Quarantine
 
 Detects contradictions and evolves memories over time (requires LLM):
 
@@ -110,6 +110,54 @@ await mem.evolve('a', 'Server now runs on port 8080');
 // Old version archived with evolution history
 ```
 
+**Quarantine lane** — low-trust or structurally conflicting memories are quarantined instead of auto-superseding:
+
+```javascript
+// Store with claim metadata and provenance
+await mem.store('a', 'Server runs on port 443', {
+  claim: { subject: 'server', predicate: 'port', value: '443' },
+  provenance: { source: 'user_explicit', trust: 1.0 },
+  onConflict: 'quarantine',  // default — quarantine low-trust conflicts
+});
+
+// Review quarantined memories
+const quarantined = await mem.listQuarantined();
+await mem.reviewQuarantine(quarantined[0].id, { action: 'activate' });
+// or: { action: 'reject' } to archive it
+```
+
+### 📋 Predicate Schema Registry
+
+Define rules for how predicates handle conflicts, deduplication, and normalization:
+
+```javascript
+const mem = createMemory({
+  predicateSchemas: {
+    'preferred_language': { cardinality: 'single', conflictPolicy: 'supersede', normalize: 'lowercase_trim' },
+    'spoken_languages':   { cardinality: 'multi', dedupPolicy: 'corroborate' },
+    'salary':             { cardinality: 'single', conflictPolicy: 'require_review', normalize: 'currency' },
+  },
+});
+
+mem.registerPredicate('timezone', { cardinality: 'single', normalize: 'trim' });
+```
+
+### 🔍 Explainability API
+
+Understand why memories were returned, filtered, or superseded:
+
+```javascript
+const results = await mem.search('kuro', 'port config', { explain: true });
+console.log(results.meta);        // { query, options, resultCount, ... }
+console.log(results[0].explain);  // { retrieved, rerank, statusFilter, ... }
+
+const detail = await mem.explainMemory(memoryId);
+// { id, status, trust, confidence, provenance, claimSummary }
+
+const chain = await mem.explainSupersession(memoryId);
+// { superseded, supersededBy, trustComparison: { original, superseding, delta } }
+```
+
 ### 🌐 Multi-Agent
 
 Native support for multiple agents with cross-agent search:
@@ -199,6 +247,67 @@ const mem = createMemory({
 });
 ```
 
+### Episodes (Temporal Grouping)
+Group related memories into named episodes with time ranges:
+```javascript
+// Manual: group specific memories
+const ep = await mem.createEpisode('Deploy v2.0', [id1, id2, id3], { tags: ['deploy'] });
+
+// Auto-capture: grab all memories in a time window
+const ep2 = await mem.captureEpisode('kuro', 'Morning standup', {
+  start: '2026-02-25T09:00:00Z',
+  end: '2026-02-25T10:00:00Z',
+});
+
+// Search within an episode
+const results = await mem.searchEpisode(ep.id, 'database migration');
+
+// LLM-generated summary
+const { summary } = await mem.summarizeEpisode(ep.id);
+```
+
+### Memory Compression
+Consolidate redundant memories into digests (extractive or LLM-based):
+```javascript
+// Compress specific memories
+const digest = await mem.compress([id1, id2, id3], {
+  method: 'llm',             // 'extractive' (default) or 'llm'
+  archiveOriginals: true,     // archive source memories after compression
+});
+
+// Compress an episode or cluster
+await mem.compressEpisode(episodeId);
+await mem.compressCluster(0);  // by cluster index from clusters()
+
+// Auto-compress stale clusters
+const result = await mem.autoCompress({ minClusterSize: 3, maxDigests: 5 });
+// { compressed: 3, totalSourceMemories: 15, digests: [...] }
+```
+
+### Labeled Clusters
+Organize memories into persistent named groups:
+```javascript
+const cl = await mem.createCluster('Security findings', [id1, id2]);
+await mem.refreshCluster(cl.id);    // Re-expand via BFS traversal
+await mem.autoLabelClusters();       // LLM labels unlabeled clusters
+```
+
+### Consolidation (Full Maintenance)
+Single call that runs the complete memory maintenance lifecycle:
+```javascript
+const report = await mem.consolidate({
+  dedupThreshold: 0.95,       // Similarity threshold for dedup
+  compressAge: 30,            // Compress clusters older than N days
+  pruneSuperseded: true,      // Archive old superseded memories
+  pruneQuarantined: false,    // Archive old unreviewed quarantined memories
+  pruneAge: 90,               // Archive superseded older than N days
+  dryRun: false,              // Preview without changes
+});
+// report: { deduplicated, contradictions, corroborated, compressed, pruned, before, after, duration_ms }
+```
+
+Phases: dedup → contradiction resolution → cross-source corroboration → compress stale clusters → prune.
+
 ## CLI
 
 ```bash
@@ -220,12 +329,14 @@ Factory function. All options are optional — zero-config returns a working ins
 
 | Method | Description |
 |--------|-------------|
-| `store(agent, text, opts?)` | Store with A-MEM auto-linking |
-| `search(agent, query, opts?)` | Semantic/keyword search (single agent) |
+| `store(agent, text, opts?)` | Store with A-MEM auto-linking. Opts: `claim`, `provenance`, `onConflict` |
+| `search(agent, query, opts?)` | Semantic/keyword search. Opts: `explain`, `statusFilter`, `sessionId` |
 | `searchAll(query, opts?)` | Cross-agent search |
 | `evolve(agent, text, opts?)` | Store with conflict resolution |
 | `ingest(agent, text, opts?)` | Bulk extract facts and store |
 | `context(agent, query, opts?)` | Generate context briefing |
+| `storeMany(agent, items, opts?)` | Batch store with atomic rollback |
+| `searchMany(agent, queries, opts?)` | Batch search (single embed call) |
 
 ### Graph Methods
 
@@ -245,6 +356,68 @@ Factory function. All options are optional — zero-config returns a working ins
 | `reinforce(memoryId, boost?)` | Boost memory importance |
 | `health()` | Full health report |
 | `timeline(agent?, days?)` | Date-grouped memory view |
+| `consolidate(opts?)` | Full maintenance: dedup → contradiction check → corroborate → compress → prune |
+
+### Episode Methods
+
+| Method | Description |
+|--------|-------------|
+| `createEpisode(name, ids, opts?)` | Group memories into a named episode |
+| `captureEpisode(agent, name, opts)` | Auto-capture episode from time window |
+| `getEpisode(id)` | Get episode with resolved memories |
+| `addToEpisode(id, memoryIds)` | Add memories to an episode |
+| `removeFromEpisode(id, memoryIds)` | Remove memories from an episode |
+| `listEpisodes(opts?)` | List episodes (filter by agent, tag, time) |
+| `searchEpisode(id, query, opts?)` | Semantic search within an episode |
+| `summarizeEpisode(id)` | LLM-generated episode summary |
+| `deleteEpisode(id)` | Delete episode (memories preserved) |
+
+### Compression Methods
+
+| Method | Description |
+|--------|-------------|
+| `compress(ids, opts?)` | Compress memories into a digest (extractive or LLM) |
+| `compressEpisode(id, opts?)` | Compress all memories in an episode |
+| `compressCluster(index, opts?)` | Compress an auto-detected cluster |
+| `autoCompress(opts?)` | Auto-detect and compress stale clusters |
+
+### Labeled Cluster Methods
+
+| Method | Description |
+|--------|-------------|
+| `createCluster(label, ids, opts?)` | Create a named cluster |
+| `labelCluster(index, label, opts?)` | Label an auto-detected cluster |
+| `listClusters()` | List all labeled clusters |
+| `getCluster(id)` | Get cluster with resolved memories |
+| `refreshCluster(id)` | Re-expand cluster via BFS |
+| `deleteCluster(id)` | Delete cluster (memories preserved) |
+| `autoLabelClusters(opts?)` | LLM-generated labels for unlabeled clusters |
+
+### Predicate Schema Methods
+
+| Method | Description |
+|--------|-------------|
+| `registerPredicate(name, schema)` | Register conflict/normalization rules for a predicate |
+| `registerPredicates(map)` | Bulk register from object or Map |
+| `getPredicateSchema(name)` | Get effective schema (with defaults) |
+| `listPredicateSchemas()` | List all registered schemas |
+
+### Explainability Methods
+
+| Method | Description |
+|--------|-------------|
+| `explainMemory(memoryId)` | Trust, confidence, provenance, claim summary |
+| `explainSupersession(memoryId)` | Supersession chain with trust comparison |
+
+### Quarantine Methods
+
+| Method | Description |
+|--------|-------------|
+| `quarantine(memoryId, opts?)` | Manually quarantine an active memory |
+| `listQuarantined(opts?)` | List quarantined memories (filterable by agent) |
+| `reviewQuarantine(memoryId, opts)` | Activate or reject a quarantined memory |
+| `pendingConflicts()` | List unresolved structural conflicts |
+| `resolveConflict(conflictId, opts)` | Resolve a pending conflict |
 
 ### Advanced: Bring Your Own Providers
 
@@ -252,7 +425,10 @@ Factory function. All options are optional — zero-config returns a working ins
 import { MemoryGraph } from '@jeremiaheth/neolata-mem';
 
 const graph = new MemoryGraph({
-  storage: myCustomStorage,      // { load, save, loadArchive, saveArchive, genId }
+  storage: myCustomStorage,      // { load, save, loadArchive, saveArchive, genId,
+                                 //   loadEpisodes?, saveEpisodes?, genEpisodeId?,
+                                 //   loadClusters?, saveClusters?, genClusterId?,
+                                 //   loadPendingConflicts?, savePendingConflicts? }
   embeddings: myCustomEmbedder,  // { embed(texts) → number[][] }
   extraction: myExtractor,       // { extract(text) → Fact[] }
   llm: myLLM,                   // { chat(prompt) → string }
@@ -264,16 +440,29 @@ const graph = new MemoryGraph({
 
 ```
 Text → [Embed] → [Find Related] → [Link Bidirectionally] → [Store]
-                       ↑
-                 Existing memories
-                 with embeddings
+                       ↑                      ↓
+                 Existing memories    [Structural Conflict Check]
+                 with embeddings       (claim matching by subject/predicate)
+                                             ↓
+                                  [Trust Comparison] → quarantine or supersede
 
-Conflict Detection:
+Conflict Detection (evolve):
   New fact → [Embed] → [Find high-similarity] → [LLM: conflict/update/novel?]
     → CONFLICT: archive old, store new
     → UPDATE: modify existing in-place (with evolution history)
     → NOVEL: normal A-MEM store
 
+Structural Conflict Detection (store with claims):
+  New claim → [Match subject+predicate+scope] → [Compare trust scores]
+    → Higher trust: supersede existing
+    → Lower trust: quarantine new (or keep_active via onConflict option)
+    → Equal trust or require_review policy: add to pending conflicts
+
+Trust Score:
+  trust = sourceWeight + corroborationBonus + feedbackSignal - recencyPenalty
+  Sources: user_explicit(1.0), system(0.95), tool_output(0.85),
+           user_implicit(0.7), document(0.6), inference(0.5)
+
 Decay Cycle:
   For each memory:
     strength = (importance × ageFactor × touchFactor × categoryWeight) + linkBonus + accessBonus
@@ -291,6 +480,11 @@ Decay Cycle:
 | Graph traversal | ✅ | ❌ | ❌ | ✅ |
 | Multi-agent native | ✅ | ❌ | ❌ | ❌ |
 | Conflict resolution | ✅ | ✅ | ❌ | ❌ |
+| Quarantine lane | ✅ | ❌ | ❌ | ❌ |
+| Predicate schemas | ✅ | ❌ | ❌ | ❌ |
+| Explainability API | ✅ | ❌ | ❌ | ❌ |
+| Episodes & compression | ✅ | ❌ | ❌ | ❌ |
+| Labeled clusters | ✅ | ❌ | ❌ | ❌ |
 | Works offline | ✅ | ✅ | ✅ | ❌ |
 | No Python needed | ✅ | ❌ | ❌ | ❌ |
 | Zero-config start | ✅ | ❌ | ❌ | ❌ |