Core Concepts
Engram Memory
Engram is OPIDE's biologically-inspired memory system. 30+ Rust modules implementing a three-tier architecture modelled on how biological memory actually works — not a simple vector database with a similarity threshold.
The three tiers#
| Tier | Name | What it holds | Lifetime |
|---|---|---|---|
0 | Sensory Buffer | Raw input from the current turn — messages, tool results, recalled memories | Single turn (ring buffer, 20 items) |
1 | Working Memory | Active context with priority-based eviction and a 4,096-token budget | Current session |
2 | Long-Term Graph | Persistent episodic, knowledge, and procedural memories with decay | Permanent (with decay) |
The long-term memory graph#
Tier 2 is not a flat vector store. It is a typed graph with three interconnected node types and explicit edges between them.
Episodic memories#
What happened. Conversations, events, agent actions, results. Each episodic memory carries: an importance score (0-1), a strength value that decays via an Ebbinghaus forgetting curve, an optional vector embedding, and scope metadata linking it to a project or file.
Knowledge memories#
What is true. Subject-predicate-object triples. When a fact updates, the old knowledge node is automatically reconsolidated rather than duplicated. The graph avoids contradiction by surfacing conflicting facts during consolidation and resolving them.
Procedural memories#
How to do things. Step-by-step procedures with trigger conditions and tracked success/failure rates. The agent refines procedures over time based on which ones actually worked.
Retrieval pipeline#
Memory retrieval is a four-stage pipeline inspired by Self-RAG and CRAG research. Not every query hits the database — the gating stage catches 40% of lookups that would return nothing useful.
1. Gating#
Before any search, the intent classifier routes the query to one of five outcomes: Skip (no retrieval needed), Retrieve (standard lookup), Deep (exhaustive multi-store search), Refuse (out of scope), or Defer (wait for more context). This prevents unnecessary latency on queries where memory has nothing to add.
2. Hybrid search#
BM25 full-text search and vector semantic search run simultaneously across all three memory stores. BM25 catches exact matches and keywords. Vector search catches semantic similarity even when terminology differs. Both results are combined.
3. Reranking#
Results from BM25 and vector search are merged using Reciprocal Rank Fusion (RRF, k=60), then deduplicated using Maximal Marginal Relevance (MMR) to avoid returning near-identical memories that waste context budget.
4. Quality gating#
Each result is scored with NDCG and classified using the CRAG three-tier system: Correct (high confidence, used directly), Ambiguous (needs verification), or Incorrect (filtered out). Every retrieval call returns quality metrics alongside the results.
Consolidation and decay#
Engram runs an automatic consolidation pass every 5 minutes. This is not background garbage collection — it actively improves memory quality over time.
- ◆Pattern clustering — extracts recurring semantic patterns from episodic memories and promotes them to knowledge
- ◆Contradiction detection — finds conflicting knowledge nodes and resolves them
- ◆FadeMem decay — dual-layer Ebbinghaus forgetting curves (LML beta=0.8, SML beta=1.2) reduce strength of unused memories over time
- ◆Memory fusion — memories with cosine similarity above 0.75 are merged; superseded entries get tombstone markers
- ◆Garbage collection — runs with transactional savepoint rollback, so a failed consolidation cannot corrupt the graph
Dream Replay#
When OPIDE is idle, a background process called Dream Replay runs. Inspired by hippocampal replay in biological memory, it re-embeds memories, discovers new connections between existing nodes, and strengthens recall pathways for memories that have been accessed frequently. The result is a memory graph that improves while you are not using it.
The Memory Palace#
The Memory Palace is the visual interface to Engram. Open it from the sidebar. Five tabs:
- ◆Recall — semantic search across every memory. Type a concept and find everything the agent knows about it.
- ◆Map — live neural graph of memory connections. Nodes are memories, edges are relationships.
- ◆Atlas — scatter-plot of memory clusters by embedding similarity. See how concepts group.
- ◆Forge — create and pin structured knowledge entries manually.
- ◆Remember — capture a specific piece of context and tell the agent to keep it permanently.