Concepts

Core concepts behind MindGraph's structured semantic memory model.

Layers

MindGraph organizes knowledge into six cognitive layers that mirror how agents reason, plus an optional operational ontology layer for workspace-specific business objects (Layer 7). Each layer has its own set of node types, and queries can target a single layer or traverse across all of them.

Node Types (64)

Every node has a type that determines its layer and the shape of its properties. The 64 built-in types cover the most common knowledge structures for AI agents. Custom types are also supported via the Custom variant — pass any string as the node_type field in API requests. Custom types are the backing storage for Layer 7 (Operational Ontology) domain objects.

Every node carries universal metadata: uid, label, summary, confidence (0.0-1.0), salience (0.0-1.0), privacy, version, and timestamps.

Edge Types (108)

Edges connect nodes with typed relationships. Each edge type belongs to a category and carries its own property schema.

Search

MindGraph supports three search modes:

• Full-text search — BM25 scoring over node labels and summaries. Filter by node type and layer.
• Semantic/vector search — Embedding-powered cosine similarity search via HNSW indices. Requires embeddings to be configured and populated.
• Hybrid search — Combines BM25 and vector search with reciprocal rank fusion for best results.

Traversal

Graph traversal uses an optimized 2-query BFS: one query fetches all live edges, BFS runs in-memory, then a second query batch-fetches node metadata. This reduces traversal from O(N) database queries to exactly 2.

• Reasoning chain — Follow epistemic edges (Supports, Refutes, etc.) from a starting node.
• Neighborhood — BFS in any direction up to a given depth.
• Path finding — Find the shortest path between two nodes.
• Subgraph extraction — Get all reachable nodes and their interconnecting edges.

Versioning

MnesticDB stores knowledge bitemporally. Valid time records when a fact was true in the world; transaction time records when MindGraph learned or changed it. Every mutation creates a new append-only version, so you can inspect history, reconstruct what the system knew at an earlier point, and distinguish a corrected fact from a newly discovered fact. Each version records who made the change (changed_by) and why (reason).

Salience & Temporal Decay

Every node has a salience score (0.0-1.0) that represents contextual relevance. Salience decays over time using an exponential half-life model — just like human memory, recent knowledge surfaces first in search results.

Use POST /decay to apply decay, and optionally auto-tombstone nodes that fall below a salience threshold.

Multi-Agent Support

MindGraph resolves the acting principal from the authenticated credential; callers cannot claim a different identity by changing a request field. Access is evaluated before retrieval or mutation, and provenance records the human or agent responsible for each change.

• Spaces — Grant read or write access, with optional classification ceilings.
• Projects — Assign viewer, editor, or agent roles to a scoped source corpus.
• Tool grants — Explicitly control which native or MCP tools an agent may invoke.
• Revocation — Access changes apply on the next request; sessions do not retain stale authority.
• Provenance — Version history retains changed_by and delegated execution context.

See Governance & Access for the full authorization model.

Entity Resolution

MindGraph includes built-in entity resolution via an alias table. Register aliases for entities, resolve text to canonical UIDs (exact or fuzzy match), and merge duplicate entities — edges are automatically retargeted and the duplicate is tombstoned.