# div-dev123/adam architecture

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

- Interactive diagram: https://gitdiagram.com/div-dev123/adam
- Repository: https://github.com/div-dev123/adam

## Overview

ADAM is a conversational-memory framework with an interactive research UI. In the write path, user and assistant turns are filtered, scored, assigned tiers, consolidated, and persisted with audit history. In the read path, query drift selects memory scope before hybrid retrieval, ranking, and context budgeting prepare memories for an agent response. Lifecycle management and compression maintain stored memories over time. The README documents the UI and integrations; source excerpts are partial, so some subsystem wiring is shown only where documented.

Main entry points: [`app/retrieval/retrieval.py`](https://github.com/div-dev123/adam/blob/main/app/retrieval/retrieval.py) (Retrieval Orchestrator), [`app/main.py`](https://github.com/div-dev123/adam/blob/main/app/main.py) (Runtime API), [`app/memory/consolidation.py`](https://github.com/div-dev123/adam/blob/main/app/memory/consolidation.py) (Consolidation), [`app/memory/storage.py`](https://github.com/div-dev123/adam/blob/main/app/memory/storage.py) (SQLite Memory and Audit Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and Interface"]
  node_api["Runtime API<br/>[main.py]"]
  node_webui["Research Web UI<br/>[app.js]"]
  node_settings["Runtime Configuration<br/>[config.py]"]
end

subgraph group_write["Memory Write Path"]
  node_filter_score["Filter and Score<br/>[importance.py]"]
  node_tier_policy["Initial Tiering<br/>[tiers.py]"]
  node_consolidation["Consolidation<br/>[consolidation.py]"]
  node_llm["Ollama LLM Client<br/>[client.py]"]
  node_memory_model["Memory Model<br/>[models.py]"]
  node_store[("SQLite Memory and Audit Store<br/>[storage.py]")]
end

subgraph group_read["Adaptive Retrieval"]
  node_embeddings["Embedding Service<br/>[embeddings.py]"]
  node_drift["Query Drift Detection<br/>[drift.py]"]
  node_retrieval["Retrieval Orchestrator<br/>[retrieval.py]"]
  node_hybrid["Hybrid Search<br/>[hybrid.py]"]
  node_bm25["BM25 Search<br/>[bm25.py]"]
  node_ranking["Candidate Ranking<br/>[ranking.py]"]
  node_context["Context Budgeting<br/>[context_builder.py]"]
end

subgraph group_lifecycle["Memory Lifecycle"]
  node_lifecycle["Retention and Forgetting<br/>[lifecycle.py]"]
  node_compression["Memory Compression<br/>[compression.py]"]
end

subgraph group_integrations["Agent Integrations"]
  node_langchain["LangChain Adapter"]
  node_langgraph["LangGraph Tools<br/>[langgraph_tools.py]"]
end

node_user(("User / Agent"))

node_user -->|"sends turns and queries"| node_api
node_api -->|"filters and scores turns"| node_filter_score
node_api -->|"routes memory writes"| node_consolidation
node_filter_score -->|"scores initial tier"| node_tier_policy
node_consolidation -.->|"classifies ambiguous cases"| node_llm
node_consolidation -->|"embeds incoming content"| node_embeddings
node_consolidation -->|"persists decisions"| node_store
node_consolidation -->|"creates and updates"| node_memory_model
node_api -->|"dispatches queries"| node_retrieval
node_retrieval -->|"selects adaptive scope"| node_drift
node_retrieval -->|"loads memory candidates"| node_store
node_retrieval -->|"runs hybrid search"| node_hybrid
node_hybrid -->|"scores lexical matches"| node_bm25
node_retrieval -->|"ranks candidates"| node_ranking
node_retrieval -->|"budgets prompt context"| node_context
node_retrieval -->|"embeds query text"| node_embeddings
node_api -->|"generates assistant response"| node_llm
node_api -->|"runs lifecycle policy"| node_lifecycle
node_lifecycle -->|"updates and forgets memories"| node_store
node_lifecycle -->|"requests compression"| node_compression
node_compression -->|"persists compressed state"| node_store
node_user -->|"uses research views"| node_webui
node_webui -.->|"interacts with runtime"| node_api
node_langchain -.->|"adapts memory access"| node_retrieval
node_langgraph -.->|"provides agent tools"| node_retrieval
node_settings -->|"configures runtime"| node_api

click node_api "https://github.com/div-dev123/adam/blob/main/app/main.py"
click node_webui "https://github.com/div-dev123/adam/blob/main/app/static/js/app.js"
click node_settings "https://github.com/div-dev123/adam/blob/main/app/config.py"
click node_filter_score "https://github.com/div-dev123/adam/blob/main/app/memory/importance.py"
click node_tier_policy "https://github.com/div-dev123/adam/blob/main/app/memory/tiers.py"
click node_consolidation "https://github.com/div-dev123/adam/blob/main/app/memory/consolidation.py"
click node_llm "https://github.com/div-dev123/adam/blob/main/app/llm/client.py"
click node_embeddings "https://github.com/div-dev123/adam/blob/main/app/retrieval/embeddings.py"
click node_memory_model "https://github.com/div-dev123/adam/blob/main/app/memory/models.py"
click node_store "https://github.com/div-dev123/adam/blob/main/app/memory/storage.py"
click node_drift "https://github.com/div-dev123/adam/blob/main/app/retrieval/drift.py"
click node_retrieval "https://github.com/div-dev123/adam/blob/main/app/retrieval/retrieval.py"
click node_hybrid "https://github.com/div-dev123/adam/blob/main/app/retrieval/hybrid.py"
click node_bm25 "https://github.com/div-dev123/adam/blob/main/app/retrieval/bm25.py"
click node_ranking "https://github.com/div-dev123/adam/blob/main/app/retrieval/ranking.py"
click node_context "https://github.com/div-dev123/adam/blob/main/app/retrieval/context_builder.py"
click node_lifecycle "https://github.com/div-dev123/adam/blob/main/app/memory/lifecycle.py"
click node_compression "https://github.com/div-dev123/adam/blob/main/app/memory/compression.py"
click node_langchain "https://github.com/div-dev123/adam/blob/main/app/integrations/langchain_memory.py"
click node_langgraph "https://github.com/div-dev123/adam/blob/main/app/integrations/langgraph_tools.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_api,node_webui,node_settings,node_user toneBlue
class node_filter_score,node_tier_policy,node_consolidation,node_llm,node_memory_model,node_store toneAmber
class node_embeddings,node_drift,node_retrieval,node_hybrid,node_bm25,node_ranking,node_context toneMint
class node_lifecycle,node_compression toneRose
class node_langchain,node_langgraph toneIndigo
```

## Components

### Runtime and Interface

- [Runtime API](https://github.com/div-dev123/adam/blob/main/app/main.py): `app/main.py`
- [Research Web UI](https://github.com/div-dev123/adam/blob/main/app/static/js/app.js): `app/static/js/app.js`
- [Runtime Configuration](https://github.com/div-dev123/adam/blob/main/app/config.py): `app/config.py`

### Memory Write Path

- [Filter and Score](https://github.com/div-dev123/adam/blob/main/app/memory/importance.py): `app/memory/importance.py`
- [Initial Tiering](https://github.com/div-dev123/adam/blob/main/app/memory/tiers.py): `app/memory/tiers.py`
- [Consolidation](https://github.com/div-dev123/adam/blob/main/app/memory/consolidation.py): `app/memory/consolidation.py`
- [Ollama LLM Client](https://github.com/div-dev123/adam/blob/main/app/llm/client.py): `app/llm/client.py`
- [Memory Model](https://github.com/div-dev123/adam/blob/main/app/memory/models.py): `app/memory/models.py`
- [SQLite Memory and Audit Store](https://github.com/div-dev123/adam/blob/main/app/memory/storage.py): `app/memory/storage.py`

### Adaptive Retrieval

- [Embedding Service](https://github.com/div-dev123/adam/blob/main/app/retrieval/embeddings.py): `app/retrieval/embeddings.py`
- [Query Drift Detection](https://github.com/div-dev123/adam/blob/main/app/retrieval/drift.py): `app/retrieval/drift.py`
- [Retrieval Orchestrator](https://github.com/div-dev123/adam/blob/main/app/retrieval/retrieval.py): `app/retrieval/retrieval.py`
- [Hybrid Search](https://github.com/div-dev123/adam/blob/main/app/retrieval/hybrid.py): `app/retrieval/hybrid.py`
- [BM25 Search](https://github.com/div-dev123/adam/blob/main/app/retrieval/bm25.py): `app/retrieval/bm25.py`
- [Candidate Ranking](https://github.com/div-dev123/adam/blob/main/app/retrieval/ranking.py): `app/retrieval/ranking.py`
- [Context Budgeting](https://github.com/div-dev123/adam/blob/main/app/retrieval/context_builder.py): `app/retrieval/context_builder.py`

### Memory Lifecycle

- [Retention and Forgetting](https://github.com/div-dev123/adam/blob/main/app/memory/lifecycle.py): `app/memory/lifecycle.py`
- [Memory Compression](https://github.com/div-dev123/adam/blob/main/app/memory/compression.py): `app/memory/compression.py`

### Agent Integrations

- [LangChain Adapter](https://github.com/div-dev123/adam/blob/main/app/integrations/langchain_memory.py): `app/integrations/langchain_memory.py`
- [LangGraph Tools](https://github.com/div-dev123/adam/blob/main/app/integrations/langgraph_tools.py): `app/integrations/langgraph_tools.py`

### Other components

- **User / Agent**

## Connections

- User / Agent → Runtime API: sends turns and queries (evidence: `README.md`)
- Runtime API → Filter and Score: filters and scores turns (evidence: `app/main.py`)
- Runtime API → Consolidation: routes memory writes (evidence: `app/main.py`)
- Filter and Score → Initial Tiering: scores initial tier (evidence: `README.md`)
- Consolidation → Ollama LLM Client: classifies ambiguous cases (evidence: `README.md`)
- Consolidation → Embedding Service: embeds incoming content (evidence: `app/memory/consolidation.py`)
- Consolidation → SQLite Memory and Audit Store: persists decisions (evidence: `app/memory/consolidation.py`)
- Consolidation → Memory Model: creates and updates (evidence: `app/memory/consolidation.py`)
- Runtime API → Retrieval Orchestrator: dispatches queries (evidence: `app/main.py`)
- Retrieval Orchestrator → Query Drift Detection: selects adaptive scope (evidence: `app/retrieval/retrieval.py`)
- Retrieval Orchestrator → SQLite Memory and Audit Store: loads memory candidates (evidence: `app/retrieval/retrieval.py`)
- Retrieval Orchestrator → Hybrid Search: runs hybrid search (evidence: `app/retrieval/retrieval.py`)
- Hybrid Search → BM25 Search: scores lexical matches (evidence: `app/retrieval/hybrid.py`)
- Retrieval Orchestrator → Candidate Ranking: ranks candidates (evidence: `app/retrieval/retrieval.py`)
- Retrieval Orchestrator → Context Budgeting: budgets prompt context (evidence: `app/retrieval/retrieval.py`)
- Retrieval Orchestrator → Embedding Service: embeds query text (evidence: `app/retrieval/retrieval.py`)
- Runtime API → Ollama LLM Client: generates assistant response (evidence: `app/main.py`)
- Runtime API → Retention and Forgetting: runs lifecycle policy (evidence: `app/main.py`)
- Retention and Forgetting → SQLite Memory and Audit Store: updates and forgets memories (evidence: `app/memory/lifecycle.py`)
- Retention and Forgetting → Memory Compression: requests compression (evidence: `app/memory/lifecycle.py`)
- Memory Compression → SQLite Memory and Audit Store: persists compressed state (evidence: `app/memory/compression.py`)
- User / Agent → Research Web UI: uses research views (evidence: `README.md`)
- Research Web UI → Runtime API: interacts with runtime
- LangChain Adapter → Retrieval Orchestrator: adapts memory access (evidence: `README.md`)
- LangGraph Tools → Retrieval Orchestrator: provides agent tools (evidence: `README.md`)
- Runtime Configuration → Runtime API: configures runtime (evidence: `app/main.py`)