Relevant source files

The following files were used as context for generating this wiki page: - [src/engramcp/models/nodes.py](https://github.com/jychp/engramcp/blob/main/src/engramcp/models/nodes.py) - [src/engramcp/models/relations.py](https://github.com/jychp/engramcp/blob/main/src/engramcp/models/relations.py) - [src/engramcp/models/schemas.py](https://github.com/jychp/engramcp/blob/main/src/engramcp/models/schemas.py) - [src/engramcp/engine/schemas.py](https://github.com/jychp/engramcp/blob/main/src/engramcp/engine/schemas.py) - [src/engramcp/memory/schemas.py](https://github.com/jychp/engramcp/blob/main/src/engramcp/memory/schemas.py) - [src/engramcp/models/confidence.py](https://github.com/jychp/engramcp/blob/main/src/engramcp/models/confidence.py)

# Data Models & Schemas Data Models and Schemas in EngraMCP define the foundational structure for a biomimetic memory engine. The system organizes information into a structured causal graph using Neo4j, moving beyond flat vector-based retrieval to support deep traceability, contradiction handling, and progressive abstraction. These models are divided into Pydantic-based storage schemas (nodes and relations) and interface schemas for Model Context Protocol (MCP) tools. The architecture follows a layered approach where raw "Memory Fragments" are ingested into working memory, then extracted into atomic entities and claims, and finally consolidated into a permanent knowledge graph. Every piece of knowledge is anchored by a NATO-style confidence model, ensuring that both source reliability and claim credibility are tracked throughout the memory lifecycle. Sources: [README.md:1-15](), [src/engramcp/models/nodes.py:1-15](), [CLAUDE.md:75-100]() ## Core Node Ontology The graph ontology is built upon a hierarchy of node types, all sharing a common `Memory` base label. Nodes represent atomic assertions, physical or conceptual entities, and the provenance of information. ### Base and Mixin Models All nodes in the graph inherit from `MemoryBase`, which ensures unique identification via UUIDs and basic auditing through timestamps. Nodes involving temporal data (Events, Decisions, Outcomes) utilize the `TemporalMixin`. ```mermaid classDiagram class MemoryBase { +str id +datetime created_at +datetime updated_at } class TemporalMixin { +datetime occurred_at +datetime occurred_until +TemporalPrecision temporal_precision } class MemoryNode { <> } MemoryBase <|-- Fact MemoryBase <|-- Agent MemoryBase <|-- Artifact MemoryBase <|-- Source MemoryBase <|-- TemporalMixin TemporalMixin <|-- Event TemporalMixin <|-- Decision TemporalMixin <|-- Outcome MemoryBase <|-- DerivedNode DerivedNode <|-- Pattern DerivedNode <|-- Concept DerivedNode <|-- Rule ``` Sources: [src/engramcp/models/nodes.py:70-105](), [src/engramcp/models/nodes.py:270-285]() ### Node Classifications | Category | Node Type | Description | Labels | | :--- | :--- | :--- | :--- | | **Knowledge** | `Fact` | Atomic assertions about the world. | `Memory`, `Fact` | | **Temporal** | `Event` | Occurrences at specific times/periods. | `Memory`, `Temporal`, `Event` | | **Entity** | `Agent` | Actors (People, AI agents, Systems). | `Memory`, `Agent` | | **Entity** | `Artifact` | Tangible or digital objects (Files, Docs). | `Memory`, `Artifact` | | **Provenance**| `Source` | The origin of a claim (Citation, Agent ID). | `Memory`, `Source` | | **Emergent** | `Pattern` | Recurrence detected across base nodes. | `Memory`, `Derived`, `Pattern` | | **Emergent** | `Concept` | Abstractions generalizing patterns. | `Memory`, `Derived`, `Concept` | Sources: [src/engramcp/models/nodes.py:110-265](), [assets/palette.md:25-40]() ## Relationship Models Relationships in EngraMCP define the causal and structural links between nodes. Unlike typical graphs, EngraMCP often places confidence ratings on the relationships rather than the nodes themselves, allowing the same fact to have different ratings from different sources. ### Relationship Types - **Traceability**: `SOURCED_FROM` links claims to their origin `Source`. `CITE` links sources to other sources. - **Causality**: `CAUSED_BY`, `LEADS_TO`, `PRECEDED`, and `FOLLOWED` define temporal and causal flow. - **Structural**: `CONCERNS` links claims to involved `Agent` or `Artifact` entities. - **Resolution**: `POSSIBLY_SAME_AS` tracks potential entity duplicates, while `CONTRADICTS` marks opposing claims. - **Abstraction**: `DERIVED_FROM`, `GENERALIZES`, and `INSTANCE_OF` link base claims to higher-level patterns and concepts. Sources: [src/engramcp/models/relations.py:1-120](), [CLAUDE.md:145-150]() ## Confidence & NATO Ratings EngraMCP utilizes a two-dimensional NATO confidence model to qualify information. This model consists of **Reliability** (source quality) and **Credibility** (claim truthfulness). ### NATO Rating Structure - **Reliability (A-F)**: A (Completely reliable) to F (Reliability cannot be judged). - **Credibility (1-6)**: 1 (Confirmed by other sources) to 6 (Truth cannot be judged). ```mermaid graph TD subgraph Rating["NATORating (e.g., B2)"] R[Reliability: Letter A-F] C[Credibility: Number 1-6] end R -->|Source Quality| Provenance C -->|Statement Truth| Assertion ``` | Letter | Reliability | Number | Credibility | | :--- | :--- | :--- | :--- | | **A** | Completely reliable | **1** | Confirmed by other sources | | **B** | Usually reliable | **2** | Probably true | | **C** | Fairly reliable | **3** | Possibly true | | **D** | Not usually reliable | **4** | Doubtful | | **E** | Unreliable | **5** | Improbable | | **F** | Cannot be judged | **6** | Cannot be judged | Sources: [src/engramcp/models/confidence.py:10-75](), [src/engramcp/models/nodes.py:215-225]() ## Interface Schemas (MCP) The Model Context Protocol (MCP) layer uses Pydantic schemas to validate data passing between the LLM Agent and the memory engine. ### send_memory Schema The `send_memory` tool accepts a `SendMemoryInput`, which represents a new "Memory Fragment." ```python class SendMemoryInput(BaseModel): content: str source: SourceInfo | None = None confidence_hint: Reliability | None = None agent_id: str | None = None ``` Sources: [src/engramcp/models/schemas.py:35-50](), [src/engramcp/memory/schemas.py:15-30]() ### Retrieval and Correction - **get_memory**: Uses `GetMemoryInput` to query fragments using keywords, depth-limited graph traversal, and confidence filters. - **correct_memory**: Uses `CorrectMemoryInput` to contest or retract existing nodes in the graph. Sources: [src/engramcp/models/schemas.py:55-85](), [src/engramcp/models/nodes.py:35-45]() ## Data Extraction & Consolidation During the consolidation pipeline, LLMs extract structured data from raw text fragments. This data is modeled by `ExtractionResult`, which acts as an intermediate schema before graph insertion. ```mermaid flowchart TD Frag[Memory Fragment] --> Engine[Extraction Engine] Engine --> Result[Extraction Result] subgraph Result E[Extracted Entities] C[Extracted Claims] R[Extracted Relations] end E --> Graph[(Neo4j Knowledge Graph)] C --> Graph R --> Graph ``` - **ExtractedEntity**: Captures entity names, types (Agent/Artifact), and properties. - **ExtractedClaim**: Captures content, claim type (Fact/Event/Observation), and involved entities. - **ExtractedRelation**: Captures directed links between extracted entities. Sources: [src/engramcp/engine/schemas.py:15-115](), [src/engramcp/engine/consolidation.py:115-160]() ## Conclusion The Data Models & Schemas of EngraMCP provide a rigorous framework for modeling agent memory. By combining a flexible Neo4j-based node ontology with a strict NATO confidence model and structured MCP interfaces, the system ensures that every "memory" is not just a vector but a traceable, verifiable, and abstractable piece of a larger causal knowledge base.