0.2 MentisDB Mental Model

MentisDB has six core concepts. Once you understand them, the entire API surface becomes obvious. Most of the time, you'll work with four of them: Thought, Chain, Agent, and Retrieval.

1. Thought

A thought is one durable memory record. It's the atomic unit of memory. Every thought has:

content — the actual memory text
thought_type — a semantic type from a fixed ontology (Decision, Insight, Mistake, Correction, Constraint, PreferenceUpdate, Summary, Question, Wonder, LessonLearned, StateSnapshot, Plan, Subgoal, TaskComplete, LLMExtracted, AssumptionInvalidated)
role — Memory (default), Summary, Compression, Checkpoint, Handoff, Retrospective
concepts — semantic concepts (free-form tags for ideas, e.g. "authentication", "rate-limiting")
tags — short labels (e.g. "prod", "incident-2026-05-03")
importance — 0.0 to 1.0, used for ranking and retention
confidence — 0.0 to 1.0, used for trust weighting
refs — pointers to prior thoughts (intra-chain indices or cross-chain UUIDs)
valid_at / invalid_at — temporal bounds for facts that change over time
entity_type — domain-specific categorization (e.g. "architecture_decision", "user_preference")
source_episode — provenance: which session, turn, or external event produced this

Example:

ThoughtInput::new(ThoughtType::Decision,
    "Use Postgres over DynamoDB for the user-events table. \
     DynamoDB's single-region eventual consistency caused \
     two production incidents in Q1."
).with_concepts(["database", "consistency", "production"])
 .with_importance(0.9)
 .with_confidence(0.85)
 .with_tags(["prod", "architecture"]);

2. Chain

A chain is the append-only, hash-chained log of thoughts. It's the canonical source of truth. Every thought gets a stable UUID, a monotonic append-order index, and a hash that includes the previous thought's hash.

This hash chain is the key integrity primitive. If anyone — including a buggy agent — modifies or removes a thought, the chain becomes invalid. The library verifies integrity on every load and provides explicit verification helpers.

Why append-only? Memory that can be silently edited isn't memory — it's a journal that someone can rewrite. The append-only constraint is what makes MentisDB an audit log, not just a key-value store. Corrections are new thoughts that Supersedes the old ones; mistakes are Mistake thoughts that point to the failing thought.

Chains are identified by a chain_key string. One process can hold many chains. A chain can be:

In-memory only — for tests and ephemeral agents
File-backed — JSONL (legacy) or binary .tcbin (default) in a directory
Federated — a branch chain with BranchesFrom pointing to a parent

3. Agent

An agent is a named writer to one or more chains. Agents have:

agent_id — stable identifier (e.g. "planner", "executor", "critic")
aliases — alternate names (e.g. "planner" might also be "architect")
description — what this agent does
owner — tenant or team identifier
public keys — for future signed-thought workflows
status — active or revoked

Agents are first-class entities. When an agent writes a thought, the thought records who wrote it. When you search, you can filter by agent. When you audit, you can ask "what did the planner decide last week?"

Multi-agent mental model: Each agent is a peer, not a hierarchy. There's no "primary" agent. The chain is the shared space. Agents can have scopes (agent-scoped thoughts visible only to themselves, user-scoped shared thoughts, session-scoped ephemeral).

4. Scope

Every thought has a scope, stored as a scope: tag:

scope:user — shared with all agents on the chain. Default.
scope:session — visible only within the creating session (identified by source_episode)
scope:agent — visible only to the creating agent

Scopes let you have private agent scratchpads alongside shared team memory on the same chain. When in doubt, use user. Use agent for private notes, debugging, or experimental reasoning. Use session for things that should expire with the conversation.

5. Retrieval

MentisDB has one ranked retrieval API that fuses three signals:

Lexical (BM25)

Classic BM25 over content, tags, concepts, agent ids, and agent registry metadata. Field-weighted: content gets weight 1.0, tags 1.6, concepts 1.4, agent id 1.5, agent registry 1.5. Good for exact matches, identifiers, proper nouns, and recall when the user knows the words they want.

Vector (cosine)

Cosine similarity over dense embeddings. MentisDB supports any embedding provider via the EmbeddingProvider trait. Built-in providers: LocalTextEmbeddingProvider (256d, zero-deps, hashed trigrams) and FastEmbed (384d, AllMiniLML6V2, downloads on first use). Good for semantic match, paraphrasing, vocabulary mismatch, and "find ideas like this one."

Graph (BFS over relations + implicit edges)

BFS over explicit refs and typed relations (DerivedFrom, CausedBy, Corrects, Supersedes, etc.), plus implicit RelatedTo edges derived from vector cosine above a threshold. Good for multi-hop questions, "what else do I need to know about X?" and following chains of reasoning.

The three are fused with Reciprocal Rank Fusion (RRF): each thought's final score is the sum of 1 / (k + rank_in_list) across the lists it appears in. Default k = 60. RRF is opt-in; you can also tune per-signal weights or use only one.

Hybrids and filters

Every retrieval accepts a ThoughtQuery filter: thought_type, role, tags, concepts, agent ids, importance, confidence, time window, as_of timestamp, scope, and free-text. Filters run first to reduce the candidate set; the three signals rank within that set.

6. Embedding provider (optional but recommended)

If you want semantic search, register an EmbeddingProvider. MentisDB will automatically build and maintain a vector sidecar file, embed new thoughts on append, and use the embeddings during ranked search. Without a provider, lexical and graph retrieval still work fully.

See 3.1 Embedding Provider Selection for the tradeoff matrix.

The full picture

┌─────────────────────────────────────────┐
│  Agents (planner, executor, critic)     │
└────────────────┬────────────────────────┘
                 │ write (append)
                 ▼
┌─────────────────────────────────────────┐
│  Chain (append-only, hash-chained)      │
│  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐       │
│  │ T₀  │→│ T₁  │→│ T₂  │→│ T₃  │ ...   │
│  └─────┘ └─────┘ └─────┘ └─────┘       │
│       (each thought: type, role,        │
│        concepts, tags, refs, etc.)      │
└────┬──────────────────────────┬─────────┘
     │                          │
     ▼ derive                  ▼ derive
┌──────────────┐         ┌──────────────┐
│ LexicalIndex │         │ VectorIndex  │
│  (BM25)      │         │ (cosine)     │
└──────┬───────┘         └──────┬───────┘
       │                        │
       └────────┬───────────────┘
                ▼
       ┌────────────────┐
       │ Ranked Fusion  │
       │ (RRF, opt-in)  │
       └────────┬───────┘
                ▼
       Top-k results → Agent

That's the entire system. Patterns in Part 1 will use these primitives in different ways. The next chapter gets you a working memory in under five minutes.