Concepts
Core concepts behind MindGraph's structured semantic memory model.
Cognitive Layers
MindGraph organizes knowledge into six semantic layers that mirror how agents reason. 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 |
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.
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.