# hydra-db/selfgraph architecture

> Architecture diagram of the GitHub repository hydra-db/selfgraph, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hydra-db/selfgraph
- Repository: https://github.com/hydra-db/selfgraph

## Overview

SelfGraph is a Python and TypeScript SDK for turning text or supplied facts into a versioned, queryable knowledge graph. The main workflow accepts input through the graph client, optionally extracts facts, resolves entities, applies ontology and temporal rules, and stores them through a pluggable graph backend; retrieval returns graph-grounded context. The product also exposes schema/answerability, maintenance, change history, CLI, and MCP capabilities. The README documents the broad workflow and capabilities; source-index references support sampled module relationships, but unsampled internals are not asserted in detail.

Main entry points: [`src/selfgraph/client.py`](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/client.py) (Graph Client), [`src/selfgraph/_ops.py`](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/_ops.py) (Graph Records), [`src/selfgraph/insert.py`](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/insert.py) (Fact Insertion), [`src/selfgraph/schema.py`](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/schema.py) (Ontology and Schema)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["SDK and Interfaces"]
  node_client["Graph Client<br/>[client.py]"]
  node_cli["CLI<br/>[cli.py]"]
  node_mcp["MCP Server<br/>[server.py]"]
end

subgraph group_knowledge["Knowledge Processing"]
  node_extract["Text Extraction<br/>[extractor.py]"]
  node_llm["LLM Adapter<br/>[base.py]"]
  node_resolution["Entity Resolution<br/>[resolution.py]"]
  node_insert["Fact Insertion<br/>[insert.py]"]
end

subgraph group_query["Query and Ontology"]
  node_ontology["Ontology and Schema<br/>[schema.py]"]
  node_retrieve["Graph Retrieval<br/>[retrieval.py]"]
  node_answerable["Answerability Check<br/>[retrieval.py]"]
end

subgraph group_state["Graph State"]
  node_contradiction["Temporal Contradictions<br/>[contradiction.py]"]
  node_maintenance["Graph Maintenance<br/>[_maintenance.py]"]
  node_history["Diff and Export<br/>[_diff.py]"]
  node_records["Graph Records<br/>[_ops.py]"]
end

subgraph group_storage["Graph Backends"]
  node_neo4j[("Neo4j / Bolt<br/>[cypher.py]")]
  node_falkor[("FalkorDB<br/>[falkordb.py]")]
  node_hydra[("HydraDB<br/>[hydradb.py]")]
  node_kuzu[("Kuzu<br/>[kuzu.py]")]
end

node_user(("Application or Agent"))
node_llmservice{{"LLM Provider"}}

node_user -->|"uses"| node_client
node_user -->|"invokes"| node_cli
node_user -->|"connects"| node_mcp
node_client -->|"inserts text"| node_extract
node_extract -.->|"uses optionally"| node_llm
node_llm -.->|"calls optionally"| node_llmservice
node_client -->|"inserts facts"| node_insert
node_insert -.->|"resolves entities"| node_resolution
node_insert -.->|"applies schema"| node_ontology
node_insert -.->|"checks conflicts"| node_contradiction
node_insert -.->|"writes graph"| node_records
node_client -->|"retrieves context"| node_retrieve
node_retrieve -->|"grounds terms"| node_ontology
node_client -->|"checks question"| node_answerable
node_answerable -.->|"checks grounding"| node_ontology
node_client -->|"manages graph"| node_maintenance
node_client -->|"gets changes"| node_history
node_maintenance -->|"updates graph"| node_records
node_history -.->|"reads changes"| node_records
node_records -.->|"persists through"| node_neo4j
node_records -.->|"persists through"| node_falkor
node_records -.->|"persists through"| node_hydra
node_records -.->|"persists through"| node_kuzu
node_mcp -->|"serves API"| node_client

click node_client "https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/client.py"
click node_cli "https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/cli.py"
click node_mcp "https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/mcp/server.py"
click node_extract "https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/extraction/extractor.py"
click node_llm "https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/llm/base.py"
click node_resolution "https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/resolution.py"
click node_insert "https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/insert.py"
click node_ontology "https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/schema.py"
click node_retrieve "https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/retrieval.py"
click node_answerable "https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/retrieval.py"
click node_contradiction "https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/contradiction.py"
click node_maintenance "https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/_maintenance.py"
click node_history "https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/_diff.py"
click node_records "https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/_ops.py"
click node_neo4j "https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/stores/cypher.py"
click node_falkor "https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/stores/falkordb.py"
click node_hydra "https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/stores/hydradb.py"
click node_kuzu "https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/stores/kuzu.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_cli,node_mcp toneBlue
class node_extract,node_llm,node_resolution,node_insert toneAmber
class node_ontology,node_retrieve,node_answerable toneMint
class node_contradiction,node_maintenance,node_history,node_records toneRose
class node_neo4j,node_falkor,node_hydra,node_kuzu,node_user,node_llmservice toneIndigo
```

## Components

### SDK and Interfaces

- [Graph Client](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/client.py): `src/selfgraph/client.py`
- [CLI](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/cli.py): `src/selfgraph/cli.py`
- [MCP Server](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/mcp/server.py): `src/selfgraph/mcp/server.py`

### Knowledge Processing

- [Text Extraction](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/extraction/extractor.py): `src/selfgraph/extraction/extractor.py`
- [LLM Adapter](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/llm/base.py): `src/selfgraph/llm/base.py`
- [Entity Resolution](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/resolution.py): `src/selfgraph/resolution.py`
- [Fact Insertion](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/insert.py): `src/selfgraph/insert.py`

### Query and Ontology

- [Ontology and Schema](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/schema.py): `src/selfgraph/schema.py`
- [Graph Retrieval](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/retrieval.py): `src/selfgraph/retrieval.py`
- [Answerability Check](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/retrieval.py): `src/selfgraph/retrieval.py`

### Graph State

- [Temporal Contradictions](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/contradiction.py): `src/selfgraph/contradiction.py`
- [Graph Maintenance](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/_maintenance.py): `src/selfgraph/_maintenance.py`
- [Diff and Export](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/_diff.py): `src/selfgraph/_diff.py`
- [Graph Records](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/_ops.py): `src/selfgraph/_ops.py`

### Graph Backends

- [Neo4j / Bolt](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/stores/cypher.py): `src/selfgraph/stores/cypher.py`
- [FalkorDB](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/stores/falkordb.py): `src/selfgraph/stores/falkordb.py`
- [HydraDB](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/stores/hydradb.py): `src/selfgraph/stores/hydradb.py`
- [Kuzu](https://github.com/hydra-db/selfgraph/blob/main/src/selfgraph/stores/kuzu.py): `src/selfgraph/stores/kuzu.py`

### Other components

- **Application or Agent**
- **LLM Provider**

## Connections

- Application or Agent → Graph Client: uses (evidence: `README.md`)
- Application or Agent → CLI: invokes (evidence: `README.md`)
- Application or Agent → MCP Server: connects (evidence: `README.md`)
- Graph Client → Text Extraction: inserts text (evidence: `src/selfgraph/client.py`)
- Text Extraction → LLM Adapter: uses optionally (evidence: `src/selfgraph/extraction/extractor.py`)
- LLM Adapter → LLM Provider: calls optionally (evidence: `README.md`)
- Graph Client → Fact Insertion: inserts facts (evidence: `README.md`)
- Fact Insertion → Entity Resolution: resolves entities (evidence: `README.md`)
- Fact Insertion → Ontology and Schema: applies schema (evidence: `src/selfgraph/schema.py`)
- Fact Insertion → Temporal Contradictions: checks conflicts (evidence: `README.md`)
- Fact Insertion → Graph Records: writes graph (evidence: `README.md`)
- Graph Client → Graph Retrieval: retrieves context (evidence: `README.md`)
- Graph Retrieval → Ontology and Schema: grounds terms (evidence: `src/selfgraph/retrieval.py`)
- Graph Client → Answerability Check: checks question (evidence: `README.md`)
- Answerability Check → Ontology and Schema: checks grounding (evidence: `README.md`)
- Graph Client → Graph Maintenance: manages graph (evidence: `src/selfgraph/client.py`)
- Graph Client → Diff and Export: gets changes (evidence: `README.md`)
- Graph Maintenance → Graph Records: updates graph (evidence: `src/selfgraph/resources/maintenance.py`)
- Diff and Export → Graph Records: reads changes (evidence: `README.md`)
- Graph Records → Neo4j / Bolt: persists through (evidence: `README.md`)
- Graph Records → FalkorDB: persists through (evidence: `README.md`)
- Graph Records → HydraDB: persists through (evidence: `README.md`)
- Graph Records → Kuzu: persists through (evidence: `README.md`)
- MCP Server → Graph Client: serves API (evidence: `src/selfgraph/mcp/server.py`)
