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.
| Layer | Purpose | Node Types |
|---|---|---|
| Reality | Raw observations & sources | Source, Snippet, Person, Organization, Nation, Event, Place, Concept, Entity, Observation, Document, Chunk |
| Epistemic | Reasoning & knowledge | Claim, Evidence, Warrant, Argument, Hypothesis, Theory, Paradigm, Anomaly, Method, Experiment, Assumption, Question, OpenQuestion, Analogy, Pattern, Mechanism, Model, ModelEvaluation, InferenceChain, SensitivityAnalysis, ReasoningStrategy, Theorem, Equation |
| Intent | Goals & decisions | Goal, Project, Decision, Option, Constraint, Milestone |
| Action | Affordances & workflows | Affordance, Flow, FlowStep, Control, RiskAssessment |
| Memory | Persistence & recall | Session, Trace, Summary, Preference, MemoryPolicy, Journal |
| Agent | Control plane | Agent, Task, Plan, PlanStep, Approval, Policy, Execution, SafetyBudget |
| Ontology (L7) | Operational domain objects | Workspace-defined types like Client, Supplier, Patient, Contract — see Operational Ontology |
Node Types (60)
Every node has a type that determines its layer and the shape of its properties. The 60 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 (95)
Edges connect nodes with typed relationships. Each edge type belongs to a category and carries its own property schema.
| Category | Edge Types |
|---|---|
| Structural (6) | ExtractedFrom, PartOf, HasPart, InstanceOf, Contains, ChunkOf |
| Epistemic (31) | Supports, Refutes, Justifies, HasPremise, HasConclusion, HasWarrant, Rebuts, Assumes, Tests, Produces, UsesMethod, Addresses, Generates, Extends, Supersedes, Contradicts, AnomalousTo, AnalogousTo, Instantiates, TransfersTo, Evaluates, Outperforms, FailsOn, HasChainStep, PropagatesUncertaintyTo, SensitiveTo, RobustAcross, Describes, DerivedFrom, ReliesOn, ProvenBy |
| Provenance (5) | ProposedBy, AuthoredBy, CitedBy, BelievedBy, ConsensusIn |
| Intent (10) | DecomposesInto, MotivatedBy, HasOption, DecidedOn, DecidedBy, ConstrainedBy, Blocks, Informs, RelevantTo, DependsOn |
| Action (5) | AvailableOn, ComposedOf, StepUses, RiskAssessedBy, Controls |
| Memory (5) | CapturedIn, TraceEntry, Summarizes, Recalls, GovernedBy |
| Agent (10) | AssignedTo, PlannedBy, HasStep, Targets, RequiresApproval, ExecutedBy, ExecutionOf, ProducesNode, GovernedByPolicy, BudgetFor |
| Temporal (1) | Follows |
| Entity Relations (22) | WorksFor, AffiliatedWith, About, KnownBy, MemberOf, LeaderOf, FoundedBy, BasedIn, CitizenOf, LocatedIn, OccurredAt, ParticipatedIn, AlliedWith, RivalOf, ReportsTo, Endorses, Criticizes, RelatedTo, ExpertIn, OperatesIn, Strengthens, Challenges |
Search
MindGraph supports two 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
Every mutation to a node or edge creates a new version snapshot in an append-only history. You can retrieve the full history or a point-in-time snapshot at any version number. 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 tracks agent identity on every mutation. Each agent sees the full graph but owns its changes. The agent identity is set via the agent_id field in API requests.
- Agent handle — Scoped access with automatic
changed_bytracking. - Sub-agents — Hierarchical agent identities for complex systems.
- Agent nodes — Query all nodes created by a specific agent.
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.
props object, see the Node Props Reference in the API Reference. For endpoint usage patterns, see Agent Memory Patterns.