How div-dev123/adam works
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: retrieval.py Retrieval Orchestrator · main.py Runtime API · consolidation.py Consolidation · storage.py SQLite Memory and Audit Store
Components 21
Runtime and Interface
- Runtime API
app/main.py - Research Web UI
app/static/js/app.js - Runtime Configuration
app/config.py
Memory Write Path
- Filter and Score
app/memory/importance.py - Initial Tiering
app/memory/tiers.py - Consolidation
app/memory/consolidation.py - Ollama LLM Client
app/llm/client.py - Memory Model
app/memory/models.py - SQLite Memory and Audit Store
app/memory/storage.py
Adaptive Retrieval
- Embedding Service
app/retrieval/embeddings.py - Query Drift Detection
app/retrieval/drift.py - Retrieval Orchestrator
app/retrieval/retrieval.py - Hybrid Search
app/retrieval/hybrid.py - BM25 Search
app/retrieval/bm25.py - Candidate Ranking
app/retrieval/ranking.py - Context Budgeting
app/retrieval/context_builder.py
Memory Lifecycle
- Retention and Forgetting
app/memory/lifecycle.py - Memory Compression
app/memory/compression.py
Agent Integrations
- LangChain Adapter
app/integrations/langchain_memory.py - LangGraph Tools
app/integrations/langgraph_tools.py
Other components
- User / Agent
Connections 26
- User / Agent → Runtime API: sends turns and queries
README.md - Runtime API → Filter and Score: filters and scores turns
app/main.py - Runtime API → Consolidation: routes memory writes
app/main.py - Filter and Score → Initial Tiering: scores initial tier
README.md - Consolidation → Ollama LLM Client: classifies ambiguous cases
README.md - Consolidation → Embedding Service: embeds incoming content
app/memory/consolidation.py - Consolidation → SQLite Memory and Audit Store: persists decisions
app/memory/consolidation.py - Consolidation → Memory Model: creates and updates
app/memory/consolidation.py - Runtime API → Retrieval Orchestrator: dispatches queries
app/main.py - Retrieval Orchestrator → Query Drift Detection: selects adaptive scope
app/retrieval/retrieval.py - Retrieval Orchestrator → SQLite Memory and Audit Store: loads memory candidates
app/retrieval/retrieval.py - Retrieval Orchestrator → Hybrid Search: runs hybrid search
app/retrieval/retrieval.py - Hybrid Search → BM25 Search: scores lexical matches
app/retrieval/hybrid.py - Retrieval Orchestrator → Candidate Ranking: ranks candidates
app/retrieval/retrieval.py - Retrieval Orchestrator → Context Budgeting: budgets prompt context
app/retrieval/retrieval.py - Retrieval Orchestrator → Embedding Service: embeds query text
app/retrieval/retrieval.py - Runtime API → Ollama LLM Client: generates assistant response
app/main.py - Runtime API → Retention and Forgetting: runs lifecycle policy
app/main.py - Retention and Forgetting → SQLite Memory and Audit Store: updates and forgets memories
app/memory/lifecycle.py - Retention and Forgetting → Memory Compression: requests compression
app/memory/lifecycle.py - Memory Compression → SQLite Memory and Audit Store: persists compressed state
app/memory/compression.py - User / Agent → Research Web UI: uses research views
README.md - Research Web UI → Runtime API: interacts with runtime
- LangChain Adapter → Retrieval Orchestrator: adapts memory access
README.md - LangGraph Tools → Retrieval Orchestrator: provides agent tools
README.md - Runtime Configuration → Runtime API: configures runtime
app/main.py