Core concepts

Memory types and the graph

Typed memories, typed weighted edges, and how the graph is walked.

llms.txt

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 every process_turn call 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 TypeDescriptionBelief Effect
SupersedesNewer memory replaces an older oneOlder memory closed (valid_until set), kept for history
ContradictsMemory conflicts with anotherRecords a flagged conflict; both memories stay valid
SupportsMemory reinforces anotherCarries half of a confidence drop to the dependent, times the edge weight
RelatedGeneral associationNone
CausedCausal relationshipCarries 0.9 of a confidence drop to the dependent, times the edge weight
BeforeSequential / temporal orderingNone
DerivedMemory derived / inferred from anotherNone
PartOfMemory is a component of anotherNone

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. Contradicts and Supersedes edges 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_affected memories (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) and belief_propagation_min_delta (default 0.05, the smallest root change that propagates) decide when it fires; CognitiveConfig::belief_propagation (its edge_types, damping factors, depth and max_affected) decides how it spreads.