# jdhayesbc/awareness architecture

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

- Interactive diagram: https://gitdiagram.com/jdhayesbc/awareness
- Repository: https://github.com/jdhayesbc/awareness

## Overview

Awareness provides persistent identity and memory for AI entities. The central documented workflow captures conversations, extracts and stores meaning across searchable memory layers, then restores continuity across sessions and channels. The PPS HTTP server is the runtime entry point for memory tools; its excerpt confirms raw-message capture, while the index shows its references to other layers. Haven supplies private chat, and image generation and repository RAG are distinct product capabilities. Several subsystem links are documented only at a high level; those are marked unverified rather than inferred from filenames.

Main entry points: [`pps/docker/server_http.py`](https://github.com/jdhayesbc/awareness/blob/master/pps/docker/server_http.py) (PPS HTTP Server), [`haven/server.py`](https://github.com/jdhayesbc/awareness/blob/master/haven/server.py) (Haven Server), [`daemon/lyra_daemon.py`](https://github.com/jdhayesbc/awareness/blob/master/daemon/lyra_daemon.py) (Lyra Daemon), [`rag-service/app/main.py`](https://github.com/jdhayesbc/awareness/blob/master/rag-service/app/main.py) (RAG Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Entity Runtime"]
  node_daemon["Lyra Daemon<br/>[lyra_daemon.py]"]
  node_invoker["Claude Invoker<br/>[invoker.py]"]
end

subgraph group_memory["Persistent Memory"]
  node_pps["PPS HTTP Server<br/>[server_http.py]"]
  node_raw[("Raw Capture<br/>[raw_capture.py]")]
  node_anchors[("Core Anchors")]
  node_graph[("Knowledge Graph<br/>[rich_texture_v2.py]")]
  node_customgraph[("Custom Graph<br/>[custom_graph.py]")]
  node_summaries[("Rolling Summaries")]
  node_inventory[("Categorical Inventory<br/>[inventory.py]")]
  node_techrag[("Technical RAG<br/>[tech_rag.py]")]
end

subgraph group_haven["Haven Chat"]
  node_haven_server["Haven Server<br/>[server.py]"]
  node_haven_db[("Haven Database<br/>[db.py]")]
  node_haven_bridge["Haven Bridge<br/>[bridge.py]"]
  node_haven_bot["Haven Bot<br/>[bot.py]"]
end

subgraph group_capabilities["Retrieval and Media"]
  node_image_pipeline["Image Pipeline<br/>[pipeline.py]"]
  node_renderer["Image Renderers<br/>[base.py]"]
  node_rag_service["RAG Service<br/>[main.py]"]
  node_rag_engine["RAG Engine<br/>[rag_engine.py]"]
  node_rag_storage[("RAG Metadata Store<br/>[storage.py]")]
end

node_entity(("AI Entity"))

node_entity -.->|"uses sessions"| node_daemon
node_daemon -.->|"invokes model"| node_invoker
node_daemon -.->|"requests memory"| node_pps
node_pps -->|"stores messages"| node_raw
node_pps -->|"uses layer"| node_anchors
node_pps -->|"uses layer"| node_graph
node_pps -->|"uses layer"| node_summaries
node_pps -->|"uses layer"| node_inventory
node_pps -->|"uses layer"| node_techrag
node_pps -->|"uses graph"| node_customgraph
node_entity -->|"chats through"| node_haven_server
node_haven_server -->|"reads and writes"| node_haven_db
node_haven_server -->|"uses bridge"| node_haven_bridge
node_haven_bot -.->|"connects chat"| node_haven_server
node_entity -.->|"requests images"| node_image_pipeline
node_image_pipeline -->|"dispatches render"| node_renderer
node_entity -.->|"queries documents"| node_rag_service
node_rag_service -->|"runs retrieval"| node_rag_engine
node_rag_service -->|"stores metadata"| node_rag_storage

click node_daemon "https://github.com/jdhayesbc/awareness/blob/master/daemon/lyra_daemon.py"
click node_invoker "https://github.com/jdhayesbc/awareness/blob/master/daemon/cc_invoker/invoker.py"
click node_pps "https://github.com/jdhayesbc/awareness/blob/master/pps/docker/server_http.py"
click node_raw "https://github.com/jdhayesbc/awareness/blob/master/pps/layers/raw_capture.py"
click node_anchors "https://github.com/jdhayesbc/awareness/blob/master/pps/layers/core_anchors_chroma.py"
click node_graph "https://github.com/jdhayesbc/awareness/blob/master/pps/layers/rich_texture_v2.py"
click node_customgraph "https://github.com/jdhayesbc/awareness/blob/master/pps/layers/custom_graph.py"
click node_summaries "https://github.com/jdhayesbc/awareness/blob/master/pps/layers/message_summaries.py"
click node_inventory "https://github.com/jdhayesbc/awareness/blob/master/pps/layers/inventory.py"
click node_techrag "https://github.com/jdhayesbc/awareness/blob/master/pps/layers/tech_rag.py"
click node_haven_server "https://github.com/jdhayesbc/awareness/blob/master/haven/server.py"
click node_haven_db "https://github.com/jdhayesbc/awareness/blob/master/haven/db.py"
click node_haven_bridge "https://github.com/jdhayesbc/awareness/blob/master/haven/bridge.py"
click node_haven_bot "https://github.com/jdhayesbc/awareness/blob/master/haven/bot.py"
click node_image_pipeline "https://github.com/jdhayesbc/awareness/blob/master/image_gen/pipeline.py"
click node_renderer "https://github.com/jdhayesbc/awareness/blob/master/image_gen/renderers/base.py"
click node_rag_service "https://github.com/jdhayesbc/awareness/blob/master/rag-service/app/main.py"
click node_rag_engine "https://github.com/jdhayesbc/awareness/blob/master/rag-service/app/rag_engine.py"
click node_rag_storage "https://github.com/jdhayesbc/awareness/blob/master/rag-service/app/storage.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_daemon,node_invoker toneBlue
class node_pps,node_raw,node_anchors,node_graph,node_customgraph,node_summaries,node_inventory,node_techrag toneAmber
class node_haven_server,node_haven_db,node_haven_bridge,node_haven_bot toneMint
class node_image_pipeline,node_renderer,node_rag_service,node_rag_engine,node_rag_storage toneRose
class node_entity toneIndigo
```

## Components

### Entity Runtime

- [Lyra Daemon](https://github.com/jdhayesbc/awareness/blob/master/daemon/lyra_daemon.py): `daemon/lyra_daemon.py`
- [Claude Invoker](https://github.com/jdhayesbc/awareness/blob/master/daemon/cc_invoker/invoker.py): `daemon/cc_invoker/invoker.py`

### Persistent Memory

- [PPS HTTP Server](https://github.com/jdhayesbc/awareness/blob/master/pps/docker/server_http.py): `pps/docker/server_http.py`
- [Raw Capture](https://github.com/jdhayesbc/awareness/blob/master/pps/layers/raw_capture.py): `pps/layers/raw_capture.py`
- [Core Anchors](https://github.com/jdhayesbc/awareness/blob/master/pps/layers/core_anchors_chroma.py): `pps/layers/core_anchors_chroma.py`
- [Knowledge Graph](https://github.com/jdhayesbc/awareness/blob/master/pps/layers/rich_texture_v2.py): `pps/layers/rich_texture_v2.py`
- [Custom Graph](https://github.com/jdhayesbc/awareness/blob/master/pps/layers/custom_graph.py): `pps/layers/custom_graph.py`
- [Rolling Summaries](https://github.com/jdhayesbc/awareness/blob/master/pps/layers/message_summaries.py): `pps/layers/message_summaries.py`
- [Categorical Inventory](https://github.com/jdhayesbc/awareness/blob/master/pps/layers/inventory.py): `pps/layers/inventory.py`
- [Technical RAG](https://github.com/jdhayesbc/awareness/blob/master/pps/layers/tech_rag.py): `pps/layers/tech_rag.py`

### Haven Chat

- [Haven Server](https://github.com/jdhayesbc/awareness/blob/master/haven/server.py): `haven/server.py`
- [Haven Database](https://github.com/jdhayesbc/awareness/blob/master/haven/db.py): `haven/db.py`
- [Haven Bridge](https://github.com/jdhayesbc/awareness/blob/master/haven/bridge.py): `haven/bridge.py`
- [Haven Bot](https://github.com/jdhayesbc/awareness/blob/master/haven/bot.py): `haven/bot.py`

### Retrieval and Media

- [Image Pipeline](https://github.com/jdhayesbc/awareness/blob/master/image_gen/pipeline.py): `image_gen/pipeline.py`
- [Image Renderers](https://github.com/jdhayesbc/awareness/blob/master/image_gen/renderers/base.py): `image_gen/renderers/base.py`
- [RAG Service](https://github.com/jdhayesbc/awareness/blob/master/rag-service/app/main.py): `rag-service/app/main.py`
- [RAG Engine](https://github.com/jdhayesbc/awareness/blob/master/rag-service/app/rag_engine.py): `rag-service/app/rag_engine.py`
- [RAG Metadata Store](https://github.com/jdhayesbc/awareness/blob/master/rag-service/app/storage.py): `rag-service/app/storage.py`

### Other components

- **AI Entity**

## Connections

- AI Entity → Lyra Daemon: uses sessions
- Lyra Daemon → Claude Invoker: invokes model
- Lyra Daemon → PPS HTTP Server: requests memory
- PPS HTTP Server → Raw Capture: stores messages (evidence: `pps/docker/server_http.py`)
- PPS HTTP Server → Core Anchors: uses layer (evidence: `pps/docker/server_http.py`)
- PPS HTTP Server → Knowledge Graph: uses layer (evidence: `pps/docker/server_http.py`)
- PPS HTTP Server → Rolling Summaries: uses layer (evidence: `pps/docker/server_http.py`)
- PPS HTTP Server → Categorical Inventory: uses layer (evidence: `pps/docker/server_http.py`)
- PPS HTTP Server → Technical RAG: uses layer (evidence: `pps/docker/server_http.py`)
- PPS HTTP Server → Custom Graph: uses graph (evidence: `pps/docker/server_http.py`)
- AI Entity → Haven Server: chats through
- Haven Server → Haven Database: reads and writes (evidence: `haven/server.py`)
- Haven Server → Haven Bridge: uses bridge (evidence: `haven/server.py`)
- Haven Bot → Haven Server: connects chat
- AI Entity → Image Pipeline: requests images
- Image Pipeline → Image Renderers: dispatches render (evidence: `image_gen/pipeline.py`)
- AI Entity → RAG Service: queries documents
- RAG Service → RAG Engine: runs retrieval (evidence: `rag-service/app/main.py`)
- RAG Service → RAG Metadata Store: stores metadata (evidence: `rag-service/app/main.py`)