# roandejager/hillock architecture

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

- Interactive diagram: https://gitdiagram.com/roandejager/hillock
- Repository: https://github.com/roandejager/hillock

## Overview

Hillock is a local neuro-symbolic memory engine for extracting document facts and answering questions against them. Users can interact through the terminal console, an OpenAI-compatible API, or the Python engine. The main workflow ingests text or PDFs through TALON’s resolution, predicate-routing, and relation-extraction stages, then records symbolic and vector/synaptic memory. On queries, the engine selects evidence and applies a hard answerability gate before optional Ollama rendering. The graph reflects the documented workflow and shown imports/calls; internal engine details not visible in excerpts are kept at subsystem level.

Main entry points: [`engine.py`](https://github.com/roandejager/hillock/blob/master/engine.py) (Hillock engine), [`ingestor.py`](https://github.com/roandejager/hillock/blob/master/ingestor.py) (Document ingestor), [`talon_engine.py`](https://github.com/roandejager/hillock/blob/master/talon_engine.py) (TALON orchestrator), [`main.py`](https://github.com/roandejager/hillock/blob/master/main.py) (Terminal console)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["Terminal console<br/>[main.py]"]
  node_api["OpenAI API<br/>[api.py]"]
end

subgraph group_ingestion["Fact ingestion"]
  node_ingestor["Document ingestor<br/>[ingestor.py]"]
  node_talon["TALON orchestrator<br/>[talon_engine.py]"]
  node_coref["Coreference resolver<br/>[talon_engine.py]"]
  node_router["Predicate router<br/>[talon_engine.py]"]
  node_extractor["Relation extractor<br/>[talon_engine.py]"]
end

subgraph group_memory["Memory systems"]
  node_knowledge_graph[("SQLite knowledge graph<br/>[database.py]")]
  node_plasticity["Hebbian associations<br/>[plasticity.py]"]
  node_reservoir["HDC reservoir<br/>[reservoir.py]"]
end

subgraph group_answering["Query and response"]
  node_engine["Hillock engine<br/>[engine.py]"]
  node_answer_gate["Evidence selection gate<br/>[engine.py]"]
end

node_user(("User"))
node_ollama["Ollama service"]

node_user -->|"uses"| node_cli
node_user -->|"connects"| node_api
node_cli -->|"submits queries"| node_engine
node_cli -->|"starts ingestion"| node_ingestor
node_api -->|"executes turn"| node_engine
node_ingestor -->|"extracts triples"| node_talon
node_talon -->|"resolves references"| node_coref
node_talon -->|"routes predicates"| node_router
node_talon -->|"extracts relations"| node_extractor
node_ingestor -->|"resolves entities"| node_engine
node_ingestor -->|"updates HDC state"| node_reservoir
node_engine -->|"reads facts"| node_knowledge_graph
node_engine -->|"uses associations"| node_plasticity
node_engine -->|"uses HDC memory"| node_reservoir
node_engine -->|"selects evidence"| node_answer_gate
node_answer_gate -->|"renders answer"| node_ollama

click node_cli "https://github.com/roandejager/hillock/blob/master/main.py"
click node_api "https://github.com/roandejager/hillock/blob/master/api.py"
click node_ingestor "https://github.com/roandejager/hillock/blob/master/ingestor.py"
click node_talon "https://github.com/roandejager/hillock/blob/master/talon_engine.py"
click node_coref "https://github.com/roandejager/hillock/blob/master/talon_engine.py"
click node_router "https://github.com/roandejager/hillock/blob/master/talon_engine.py"
click node_extractor "https://github.com/roandejager/hillock/blob/master/talon_engine.py"
click node_engine "https://github.com/roandejager/hillock/blob/master/engine.py"
click node_answer_gate "https://github.com/roandejager/hillock/blob/master/engine.py"
click node_knowledge_graph "https://github.com/roandejager/hillock/blob/master/database.py"
click node_plasticity "https://github.com/roandejager/hillock/blob/master/plasticity.py"
click node_reservoir "https://github.com/roandejager/hillock/blob/master/reservoir.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_cli,node_api,node_user toneBlue
class node_ingestor,node_talon,node_coref,node_router,node_extractor toneAmber
class node_knowledge_graph,node_plasticity,node_reservoir toneMint
class node_engine,node_answer_gate toneRose
class node_ollama toneIndigo
```

## Components

### User interfaces

- [Terminal console](https://github.com/roandejager/hillock/blob/master/main.py): `main.py`
- [OpenAI API](https://github.com/roandejager/hillock/blob/master/api.py): `api.py`

### Fact ingestion

- [Document ingestor](https://github.com/roandejager/hillock/blob/master/ingestor.py): `ingestor.py`
- [TALON orchestrator](https://github.com/roandejager/hillock/blob/master/talon_engine.py): `talon_engine.py`
- [Coreference resolver](https://github.com/roandejager/hillock/blob/master/talon_engine.py): `talon_engine.py`
- [Predicate router](https://github.com/roandejager/hillock/blob/master/talon_engine.py): `talon_engine.py`
- [Relation extractor](https://github.com/roandejager/hillock/blob/master/talon_engine.py): `talon_engine.py`

### Memory systems

- [SQLite knowledge graph](https://github.com/roandejager/hillock/blob/master/database.py): `database.py`
- [Hebbian associations](https://github.com/roandejager/hillock/blob/master/plasticity.py): `plasticity.py`
- [HDC reservoir](https://github.com/roandejager/hillock/blob/master/reservoir.py): `reservoir.py`

### Query and response

- [Hillock engine](https://github.com/roandejager/hillock/blob/master/engine.py): `engine.py`
- [Evidence selection gate](https://github.com/roandejager/hillock/blob/master/engine.py): `engine.py`

### Other components

- **User**
- **Ollama service**

## Connections

- User → Terminal console: uses (evidence: `README.md`)
- User → OpenAI API: connects (evidence: `README.md`)
- Terminal console → Hillock engine: submits queries (evidence: `main.py`)
- Terminal console → Document ingestor: starts ingestion (evidence: `README.md`)
- OpenAI API → Hillock engine: executes turn (evidence: `api.py`)
- Document ingestor → TALON orchestrator: extracts triples (evidence: `ingestor.py`)
- TALON orchestrator → Coreference resolver: resolves references (evidence: `talon_engine.py`)
- TALON orchestrator → Predicate router: routes predicates (evidence: `talon_engine.py`)
- TALON orchestrator → Relation extractor: extracts relations (evidence: `talon_engine.py`)
- Document ingestor → Hillock engine: resolves entities (evidence: `ingestor.py`)
- Document ingestor → HDC reservoir: updates HDC state (evidence: `ingestor.py`)
- Hillock engine → SQLite knowledge graph: reads facts (evidence: `engine.py`)
- Hillock engine → Hebbian associations: uses associations (evidence: `engine.py`)
- Hillock engine → HDC reservoir: uses HDC memory (evidence: `engine.py`)
- Hillock engine → Evidence selection gate: selects evidence (evidence: `engine.py`)
- Evidence selection gate → Ollama service: renders answer (evidence: `engine.py`)
