Core concepts
Memory types and the graph
Typed memories, typed weighted edges, and how the graph is walked.
Memories are typed nodes connected by typed, weighted edges. Together they form a knowledge graph the engine walks during retrieval and belief propagation.
Memory types
semantic, facts, preferences, and knowledge. "User prefers dark mode."episodic, events and experiences. "Deployed v2.1 on Tuesday."procedural, how-to knowledge. "Run tests with pytest -x."correction, something was wrong and is now right. "API key goes in .env, not config.toml."anti_pattern, things to never do. "Never force-push to main."reasoning, why a decision was made. "Chose DynamoDB over Postgres for scaling needs."
Cognitive tiers layer on top: Working, Episodic, Semantic, Procedural, and Archival.
Memory scope
contextual(default), retrieved by semantic similarity when relevant to the current conversation.always, returned on everyprocess_turncall regardless of topic. Use for critical rules and constraints.
Entity-centric memory
Most memory systems store flat text strings. When a user says "I bought a collar for my Golden Retriever like Max," a flat system remembers the collar purchase but loses the breed. MenteDB extracts structured entities (people, pets, places, events, items, organizations) with typed attributes, resolves multiple mentions of the same entity into one node, and links entities to the memories they came from via Derived and labeled Relatededges. So "What breed is my dog?" surfaces the MAX entity with its breed attribute, even if no single turn ever said "my dog is a Golden Retriever."
Bi-temporal validity
Every memory and edge carries valid_from and valid_until timestamps. Instead of deleting outdated memories, MenteDB temporally invalidates them, preserving full history while keeping search results current. Use recall_similar_at(embedding, k, timestamp) for point-in-time queries.
Graph edges
Memories form a directed graph through typed, weighted edges. Weight runs 0.0 to 1.0, representing the strength of the relationship.
| Edge Type | Description | Belief Effect |
|---|---|---|
Supersedes | Newer memory replaces an older one | Older memory closed (valid_until set), kept for history |
Contradicts | Memory conflicts with another | Records a flagged conflict; both memories stay valid |
Supports | Memory reinforces another | Carries half of a confidence drop to the dependent, times the edge weight |
Related | General association | None |
Caused | Causal relationship | Carries 0.9 of a confidence drop to the dependent, times the edge weight |
Before | Sequential / temporal ordering | None |
Derived | Memory derived / inferred from another | None |
PartOf | Memory is a component of another | None |
Superseded memories:when memory A supersedes memory B, B's validity window is closed, so searches serve A and B stays in the history for point in time queries. The graph itself is a CSR/CSC structure with BFS/DFS traversal, so you can find paths between memories, extract subgraphs, and discover related memories through edge traversal.
Belief propagation
When write inference lowers a memory's confidence (a contradiction resolved under the default supersede policy, a value update, an LLM invalidation verdict, or a Correction), the engine halves that memory's confidence (never below 0.1) and passes a damped share of the drop to the memories that depend on it. It follows outgoing Caused edges (0.9 of the change times the edge weight) and Supports edges (0.5 of the change times the edge weight), hop by hop. With A Caused B Caused C, a drop of 0.4 at A lowers B by 0.36 and C by 0.324. It runs on both the store path and the process_turn path.
- The winner is never lowered.
ContradictsandSupersedesedges are not walked by default, so a drop on the losing memory never moves the memory that replaced it. - It is bounded. At most 5 hops, a branch stops once its change falls below 0.01, and at most
max_affectedmemories (default 64) move per propagation. Each dependent is written through the normal durable update path. - It only lowers today. Nothing in the engine raises confidence yet, so in practice propagation only lowers dependents.
- Config.
WriteInferenceConfig::belief_propagation_enabled(default on) andbelief_propagation_min_delta(default 0.05, the smallest root change that propagates) decide when it fires;CognitiveConfig::belief_propagation(itsedge_types, damping factors, depth andmax_affected) decides how it spreads.