# kkxx939-bot/habitus architecture

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

- Interactive diagram: https://gitdiagram.com/kkxx939-bot/habitus
- Repository: https://github.com/kkxx939-bot/habitus

## Overview

Habitus is a conversation-driven memory system with retrieval, prediction, and foresight capabilities. A principal path is client request through the HTTP API into conversation ingestion, ordered workflow jobs, and memory editing; recall is handled by a separate retrieval service. Model-backed behavior fusion and foresight judging are additional domain capabilities. The README is empty, and many modules were not sampled, so links are limited to relationships visible in excerpts or SOURCE INDEX references; unsampled subsystems are shown without inferred wiring.

Main entry points: [`habitus/model_client/client.py`](https://github.com/kkxx939-bot/habitus/blob/main/habitus/model_client/client.py) (Model client), [`habitus/memory/workflow/ingest.py`](https://github.com/kkxx939-bot/habitus/blob/main/habitus/memory/workflow/ingest.py) (Conversation ingestion), [`habitus/memory/retrieval/service.py`](https://github.com/kkxx939-bot/habitus/blob/main/habitus/memory/retrieval/service.py) (Memory retrieval), [`habitus/scene/concepts/author.py`](https://github.com/kkxx939-bot/habitus/blob/main/habitus/scene/concepts/author.py) (Scene concepts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api_workflow["API and workflow"]
  node_http_api["HTTP API<br/>[app.py]"]
  node_http_handlers["HTTP handlers<br/>[http.py]"]
  node_ingest["Conversation ingestion<br/>[ingest.py]"]
  node_workflow_jobs[("Workflow jobs")]
end

subgraph group_memory["Memory domain"]
  node_conversation[("Conversation journal<br/>[messages.py]")]
  node_editor["Memory editor<br/>[engine.py]"]
  node_memory_model["Memory domain model<br/>[model.py]"]
  node_retrieval["Memory retrieval<br/>[service.py]"]
  node_conversation_compaction["Conversation compaction<br/>[compaction.py]"]
  node_conversation_retention["Conversation retention<br/>[retention.py]"]
  node_conversation_segmentation["Conversation segmentation<br/>[segmentation.py]"]
end

subgraph group_reasoning["Reasoning"]
  node_fusion["Behavior fusion<br/>[service.py]"]
  node_foresight["Foresight context<br/>[context.py]"]
  node_foresight_judge["Foresight judge<br/>[service.py]"]
  node_prediction["Prediction queries<br/>[query.py]"]
  node_scene_concepts["Scene concepts<br/>[author.py]"]
  node_scene_rhythm["Scene rhythms<br/>[rhythm.py]"]
  node_prediction_nodes["Prediction nodes<br/>[nodes.py]"]
end

subgraph group_platform["Model and platform"]
  node_config["Configuration loading<br/>[loader.py]"]
  node_model_client["Model client<br/>[client.py]"]
  node_model_contracts["Model contracts<br/>[contracts.py]"]
  node_observability["Observability manager<br/>[manager.py]"]
  node_observability_contract["Observation contract<br/>[observability.py]"]
  node_structured_logging["Structured logging<br/>[logging.py]"]
end

node_client(("API client"))
node_provider["Model provider"]

node_client -->|"sends requests"| node_http_api
node_http_api -->|"routes to"| node_http_handlers
node_ingest -->|"appends messages"| node_conversation
node_ingest -->|"enqueues jobs"| node_workflow_jobs
node_editor -->|"plans memory edits"| node_memory_model
node_retrieval -->|"reads conversation"| node_conversation
node_retrieval -->|"uses memory model"| node_memory_model
node_retrieval -->|"uses compaction"| node_conversation_compaction
node_retrieval -->|"uses segmentation"| node_conversation_segmentation
node_ingest -->|"plans retention"| node_conversation_retention
node_ingest -->|"chunks messages"| node_conversation_segmentation
node_fusion -->|"requests judgement"| node_model_client
node_foresight_judge -->|"requests judgement"| node_model_client
node_scene_concepts -->|"uses model client"| node_model_client
node_scene_concepts -->|"uses rhythm concepts"| node_scene_rhythm
node_model_client -->|"uses contracts"| node_model_contracts
node_model_client -->|"calls provider"| node_provider
node_observability -->|"records events"| node_structured_logging
node_observability -->|"implements contract"| node_observability_contract
node_prediction -->|"queries nodes"| node_prediction_nodes
node_foresight -->|"uses scene views"| node_scene_concepts

click node_http_api "https://github.com/kkxx939-bot/habitus/blob/main/habitus/integrations/http_api/app.py"
click node_http_handlers "https://github.com/kkxx939-bot/habitus/blob/main/habitus/integrations/http.py"
click node_ingest "https://github.com/kkxx939-bot/habitus/blob/main/habitus/memory/workflow/ingest.py"
click node_workflow_jobs "https://github.com/kkxx939-bot/habitus/tree/main/habitus/memory/workflow/jobs"
click node_conversation "https://github.com/kkxx939-bot/habitus/blob/main/habitus/memory/conversation/messages.py"
click node_editor "https://github.com/kkxx939-bot/habitus/blob/main/habitus/memory/editor/engine.py"
click node_memory_model "https://github.com/kkxx939-bot/habitus/blob/main/habitus/memory/model.py"
click node_retrieval "https://github.com/kkxx939-bot/habitus/blob/main/habitus/memory/retrieval/service.py"
click node_conversation_compaction "https://github.com/kkxx939-bot/habitus/blob/main/habitus/memory/conversation/compaction.py"
click node_conversation_retention "https://github.com/kkxx939-bot/habitus/blob/main/habitus/memory/conversation/retention.py"
click node_conversation_segmentation "https://github.com/kkxx939-bot/habitus/blob/main/habitus/memory/conversation/segmentation.py"
click node_fusion "https://github.com/kkxx939-bot/habitus/blob/main/habitus/behavior/fusion/service.py"
click node_foresight "https://github.com/kkxx939-bot/habitus/blob/main/habitus/foresight/context.py"
click node_foresight_judge "https://github.com/kkxx939-bot/habitus/blob/main/habitus/foresight/judge/service.py"
click node_prediction "https://github.com/kkxx939-bot/habitus/blob/main/habitus/prediction/query.py"
click node_scene_concepts "https://github.com/kkxx939-bot/habitus/blob/main/habitus/scene/concepts/author.py"
click node_scene_rhythm "https://github.com/kkxx939-bot/habitus/blob/main/habitus/scene/concepts/rhythm.py"
click node_config "https://github.com/kkxx939-bot/habitus/blob/main/habitus/config/loader.py"
click node_model_client "https://github.com/kkxx939-bot/habitus/blob/main/habitus/model_client/client.py"
click node_model_contracts "https://github.com/kkxx939-bot/habitus/blob/main/habitus/model_client/contracts.py"
click node_observability "https://github.com/kkxx939-bot/habitus/blob/main/habitus/infrastructure/observability/manager.py"
click node_observability_contract "https://github.com/kkxx939-bot/habitus/blob/main/habitus/foundation/observability.py"
click node_structured_logging "https://github.com/kkxx939-bot/habitus/blob/main/habitus/infrastructure/observability/logging.py"
click node_prediction_nodes "https://github.com/kkxx939-bot/habitus/blob/main/habitus/prediction/nodes.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_http_api,node_http_handlers,node_ingest,node_workflow_jobs,node_client toneBlue
class node_conversation,node_editor,node_memory_model,node_retrieval,node_conversation_compaction,node_conversation_retention,node_conversation_segmentation toneAmber
class node_fusion,node_foresight,node_foresight_judge,node_prediction,node_scene_concepts,node_scene_rhythm,node_prediction_nodes toneMint
class node_config,node_model_client,node_model_contracts,node_observability,node_observability_contract,node_structured_logging toneRose
class node_provider toneIndigo
```

## Components

### API and workflow

- [HTTP API](https://github.com/kkxx939-bot/habitus/blob/main/habitus/integrations/http_api/app.py): `habitus/integrations/http_api/app.py`
- [HTTP handlers](https://github.com/kkxx939-bot/habitus/blob/main/habitus/integrations/http.py): `habitus/integrations/http.py`
- [Conversation ingestion](https://github.com/kkxx939-bot/habitus/blob/main/habitus/memory/workflow/ingest.py): `habitus/memory/workflow/ingest.py`
- [Workflow jobs](https://github.com/kkxx939-bot/habitus/tree/main/habitus/memory/workflow/jobs): `habitus/memory/workflow/jobs`

### Memory domain

- [Conversation journal](https://github.com/kkxx939-bot/habitus/blob/main/habitus/memory/conversation/messages.py): `habitus/memory/conversation/messages.py`
- [Memory editor](https://github.com/kkxx939-bot/habitus/blob/main/habitus/memory/editor/engine.py): `habitus/memory/editor/engine.py`
- [Memory domain model](https://github.com/kkxx939-bot/habitus/blob/main/habitus/memory/model.py): `habitus/memory/model.py`
- [Memory retrieval](https://github.com/kkxx939-bot/habitus/blob/main/habitus/memory/retrieval/service.py): `habitus/memory/retrieval/service.py`
- [Conversation compaction](https://github.com/kkxx939-bot/habitus/blob/main/habitus/memory/conversation/compaction.py): `habitus/memory/conversation/compaction.py`
- [Conversation retention](https://github.com/kkxx939-bot/habitus/blob/main/habitus/memory/conversation/retention.py): `habitus/memory/conversation/retention.py`
- [Conversation segmentation](https://github.com/kkxx939-bot/habitus/blob/main/habitus/memory/conversation/segmentation.py): `habitus/memory/conversation/segmentation.py`

### Reasoning

- [Behavior fusion](https://github.com/kkxx939-bot/habitus/blob/main/habitus/behavior/fusion/service.py): `habitus/behavior/fusion/service.py`
- [Foresight context](https://github.com/kkxx939-bot/habitus/blob/main/habitus/foresight/context.py): `habitus/foresight/context.py`
- [Foresight judge](https://github.com/kkxx939-bot/habitus/blob/main/habitus/foresight/judge/service.py): `habitus/foresight/judge/service.py`
- [Prediction queries](https://github.com/kkxx939-bot/habitus/blob/main/habitus/prediction/query.py): `habitus/prediction/query.py`
- [Scene concepts](https://github.com/kkxx939-bot/habitus/blob/main/habitus/scene/concepts/author.py): `habitus/scene/concepts/author.py`
- [Scene rhythms](https://github.com/kkxx939-bot/habitus/blob/main/habitus/scene/concepts/rhythm.py): `habitus/scene/concepts/rhythm.py`
- [Prediction nodes](https://github.com/kkxx939-bot/habitus/blob/main/habitus/prediction/nodes.py): `habitus/prediction/nodes.py`

### Model and platform

- [Configuration loading](https://github.com/kkxx939-bot/habitus/blob/main/habitus/config/loader.py): `habitus/config/loader.py`
- [Model client](https://github.com/kkxx939-bot/habitus/blob/main/habitus/model_client/client.py): `habitus/model_client/client.py`
- [Model contracts](https://github.com/kkxx939-bot/habitus/blob/main/habitus/model_client/contracts.py): `habitus/model_client/contracts.py`
- [Observability manager](https://github.com/kkxx939-bot/habitus/blob/main/habitus/infrastructure/observability/manager.py): `habitus/infrastructure/observability/manager.py`
- [Observation contract](https://github.com/kkxx939-bot/habitus/blob/main/habitus/foundation/observability.py): `habitus/foundation/observability.py`
- [Structured logging](https://github.com/kkxx939-bot/habitus/blob/main/habitus/infrastructure/observability/logging.py): `habitus/infrastructure/observability/logging.py`

### Other components

- **API client**
- **Model provider**

## Connections

- API client → HTTP API: sends requests (evidence: `habitus/integrations/http_api/app.py`)
- HTTP API → HTTP handlers: routes to (evidence: `habitus/integrations/http_api/app.py`)
- Conversation ingestion → Conversation journal: appends messages (evidence: `habitus/memory/workflow/ingest.py`)
- Conversation ingestion → Workflow jobs: enqueues jobs (evidence: `habitus/memory/workflow/ingest.py`)
- Memory editor → Memory domain model: plans memory edits (evidence: `habitus/memory/editor/engine.py`)
- Memory retrieval → Conversation journal: reads conversation (evidence: `habitus/memory/retrieval/service.py`)
- Memory retrieval → Memory domain model: uses memory model (evidence: `habitus/memory/retrieval/service.py`)
- Memory retrieval → Conversation compaction: uses compaction (evidence: `habitus/memory/retrieval/service.py`)
- Memory retrieval → Conversation segmentation: uses segmentation (evidence: `habitus/memory/retrieval/service.py`)
- Conversation ingestion → Conversation retention: plans retention (evidence: `habitus/memory/workflow/ingest.py`)
- Conversation ingestion → Conversation segmentation: chunks messages (evidence: `habitus/memory/workflow/ingest.py`)
- Behavior fusion → Model client: requests judgement (evidence: `habitus/behavior/fusion/service.py`)
- Foresight judge → Model client: requests judgement (evidence: `habitus/foresight/judge/service.py`)
- Scene concepts → Model client: uses model client (evidence: `habitus/scene/concepts/author.py`)
- Scene concepts → Scene rhythms: uses rhythm concepts (evidence: `habitus/scene/concepts/author.py`)
- Model client → Model contracts: uses contracts (evidence: `habitus/model_client/client.py`)
- Model client → Model provider: calls provider (evidence: `habitus/model_client/client.py`)
- Observability manager → Structured logging: records events (evidence: `habitus/infrastructure/observability/manager.py`)
- Observability manager → Observation contract: implements contract (evidence: `habitus/infrastructure/observability/manager.py`)
- Prediction queries → Prediction nodes: queries nodes (evidence: `habitus/prediction/query.py`)
- Foresight context → Scene concepts: uses scene views (evidence: `habitus/foresight/context.py`)
