Overview¶

Lethe --- graph-native agentic orchestrator with embedding-driven web research.

Lethe is a reasoning system that decomposes complex questions into task graphs, researches them autonomously via the web, and assembles evidence-grounded answers. It combines a single reasoning LLM, an embedding algebra control plane, and Neo4j as unified memory --- exposed through an OpenAI-compatible API.

What Problem Does Lethe Solve¶

Standard LLM wrappers treat each request as a single prompt-response pair. Complex questions --- those requiring multi-step decomposition, web research across dozens of sources, and synthesis of conflicting evidence --- exceed what a single context window can handle.

Retrieval-augmented generation (RAG) partially addresses this by injecting retrieved documents, but relies on a static retrieval step and lacks the ability to reason about what to search next. Multi-agent frameworks decompose work but often devolve into unstructured chat between agents, losing quantitative control over resource allocation and evidence quality.

Lethe addresses this by separating what to think about from how to manage the thinking:

• The LLM reasons freely, decomposes problems, and writes text.
• The orchestrator manages task selection, context budgets, convergence detection, and research navigation --- all through embedding vector computations the LLM never sees.
• Neo4j serves as persistent memory across iterations: working memory (task DAG), episodic memory (evidence nodes), and semantic memory (SIMILAR_TO edges).

This separation means the LLM's reasoning is never distorted by numeric control signals, while the orchestrator makes quantitative decisions without needing language understanding.

Core Vocabulary¶

These terms appear throughout the documentation. Each links to its detailed treatment:

Vision and Approach¶

Lethe is built on the premise that effective autonomous reasoning requires two fundamentally different computational modes operating in parallel:

Language mode handles decomposition, hypothesis generation, evidence assessment, and synthesis. These tasks require the flexible pattern matching and world knowledge that large language models provide.

Algebra mode handles resource allocation, convergence detection, relevance scoring, and navigation decisions. These tasks require precise, reproducible numeric computation that language models perform unreliably.

Most agent frameworks blur this boundary --- they prompt the LLM with budget percentages, ask it to self-assess confidence, or use it to decide when to stop. Lethe draws a hard line: the LLM never sees a number from the control plane. Budget pressure manifests as which evidence appears in context (algebra selects it), not as a textual instruction to wrap up.

This design draws from several research traditions:

• Graph-native agent memory --- Following recent work on DAG-based task decomposition and unified graph memory (HippoRAG, AriGraph), Lethe stores all state in a single Neo4j graph rather than separate vector and relational stores. Unlike HippoRAG, which uses PPR only for retrieval, Lethe also uses PPR to compose context each iteration and ties it to submodular packing under a token budget.
• Submodular optimization --- Casting context composition as knapsack-constrained submodular maximization with \((1 - 1/e)\) approximation guarantees (S-RAG, AdaGReS). Where S-RAG applies a static concept-coverage objective, Lethe uses entropy-adaptive scoring that shifts from relevance to diversity as the evidence pool grows.
• Information foraging theory --- Applying embedding-based relevance scoring (inspired by Pirolli and Card, 1999) with spectral convergence for optimal stopping. Recent work like InForage (NeurIPS 2025) uses RL to learn foraging policies; Lethe achieves comparable adaptive behavior through deterministic embedding scoring, avoiding the need for trajectory training data.
• Spectral convergence --- Using Grassmannian chordal distance to detect when the evidence subspace has stabilized, drawing on subspace tracking theory (GROUSE; Balzano et al., 2010). This provides a geometrically principled stopping signal rather than heuristic iteration caps or LLM self-assessment.

The result is a system where emergent behavior arises from the interaction between a freely reasoning LLM and a deterministic algebraic control plane, rather than from procedural scripts or hard-coded workflows.

How a Session Unfolds¶

A concrete walkthrough of one session, from question to answer:

1. Bootstrap --- The user sends a question via the OpenAI-compatible API. The orchestrator creates a root task node in Neo4j, embeds the goal, and initializes budget trackers.

2. Iteration N --- The orchestrator scores ready tasks using warped goal alignment (GA --- cosine similarity to the goal embedding), selects the most promising one, expands context via Personalized PageRank (PPR), packs it into a token budget, and serializes the subgraph as DIN-Read text (Directed Interaction Notation --- the structured protocol between LLM and orchestrator). The LLM receives this text (not numbers) and responds with DIN-Write JSON operations: create subtasks, record evidence, call web_search, or compose results.

3. Nested research --- When the LLM calls web_search, the research engine runs autonomously within that iteration: it issues SearXNG queries, navigates pages via CloakBrowser, extracts and chunks content, embeds chunks, and ingests scored evidence into the graph. The LLM is not involved in any navigation decision --- all scoring uses embedding algebra (GA ranking, spectral convergence, ψ termination).

4. Signal computation --- After operations are applied, the orchestrator runs compute_iteration_signals() over the updated graph. This produces goal alignment, novelty, stability, and reconstruction signals that drive the next iteration's task selection, context weighting, and thinking budget. The LLM never sees these signals.

5. Termination --- At the start of each iteration, the termination potential \(\psi\) (a complement-product of convergence and resource pressure, ranging from 0 to 1) is evaluated from the previous iteration's signals. When \(\psi\) exceeds the threshold (0.82), or hard budget limits are reached, the loop exits.

6. Assembly --- The compose/ module collects completed task results via DFS, orders them by MMR diversity, and composes the final answer through a dedicated LLM call with strict data-fidelity instructions. The response streams back to the client.

Throughout this process, the LLM writes natural language and structured operations; the orchestrator computes numbers. Neither crosses into the other's domain.

Key Capabilities¶

Emergent Task Decomposition¶

Given a goal, Lethe's LLM creates and restructures a task graph dynamically. There is no fixed workflow --- the agent discovers subtasks as the problem unfolds, marks dead ends, and redirects effort toward productive branches. The graph can be restructured mid-session when the topic proves deeper than initially expected. Task dependencies form a directed acyclic graph with cycle detection enforced at the graph store level.

The orchestrator acts as communication infrastructure between the LLM's present and future selves. Fields like prepared_prompt and continuation_note on task nodes let the agent leave messages for later iterations, while graph topology encodes the planning state. This means the LLM is not executing a predetermined workflow --- it is maintaining a persistent working memory that evolves across iterations, with the orchestrator providing the substrate for that memory.

Zero-LLM Web Research¶

The built-in research engine searches (via SearXNG), crawls (via stealth browser), and evaluates web content without any LLM calls. URL discovery, page scoring, and convergence-based stopping are driven entirely by embedding similarity and the same spectral algebra as the agent loop. This makes research fast (no LLM latency per page) and deterministic.

Embedding Algebra Control Plane¶

The embedding operations compute iteration signals behind a single compute_iteration_signals() interface. These signals drive task selection, budget pressure, convergence detection, and termination --- all in continuous vector space with smooth (\(C^{\infty}\)) primitives. No hard thresholds, no boolean flags. The algebra operates on the unit hypersphere \(S^{D-1}\), using geodesic rotations for exploration-to-exploitation transitions and Grassmannian chordal distance for subspace tracking.

Submodular Context Packing¶

Each iteration, Personalized PageRank expands candidates from the task graph using cosine-weighted transitions, then a greedy submodular knapsack with incremental Marginal Information Gain and AdaGReS redundancy scaling packs evidence into the token budget. The algorithm achieves a \((1 - 1/e) \approx 0.632\) approximation ratio for monotone submodular objectives (Lin and Bilmes, NAACL 2010), with an effective ratio of approximately 0.405 under MIG's redundancy penalty.

Structured LLM Interaction (DIN Protocol)¶

The LLM communicates with the orchestrator through a structured JSON protocol with eight operation types. Pydantic validation plus a repair loop ensures well-formed operations even from imperfect model output. The graph is memory --- there is no chat history, only the materialized subgraph projected into each iteration's context window.

Evidence-Grounded Composition¶

Final answers are assembled by traversing the completed task graph (DFS), ordering sections for diversity via Maximal Marginal Relevance (Carbonell and Goldstein, 1998), and composing through the LLM with explicit instructions to preserve verbatim data. Source evidence is traced through PRODUCED edges back to specific web pages.

What Makes Lethe Different¶

Architecture at a Glance¶

flowchart TB
    subgraph entry ["Entry"]
        API["Open Responses API<br/><code>POST /v1/responses</code>"]
    end

    subgraph agent ["Agent Loop"]
        Select["Task Selection<br/><small>gap-adaptive warping</small>"]
        Context["Context Composition<br/><small>PPR + knapsack + U-shape</small>"]
        LLM["LLM Reasoning<br/><small>Qwen3 + DIN protocol</small>"]
        Apply["Apply Operations<br/><small>graph mutations</small>"]
        Signals["Embedding Signals<br/><small>signal pipeline, SVD, convergence</small>"]
        Budget["Budget Manager<br/><small>smooth termination</small>"]
    end

    subgraph memory ["Unified Memory --- Neo4j"]
        Tasks["Task DAG"]
        Evidence["Evidence Nodes"]
        Similar["SIMILAR_TO Edges"]
    end

    subgraph research ["Zero-LLM Research"]
        Search["SearXNG Metasearch"]
        Browser["Stealth Browser"]
        Adapters["HTML / PDF / Video"]
    end

    Assembly["Answer Assembly<br/><small>DFS + MMR + compose</small>"]

    API --> Select
    Select --> Context --> LLM --> Apply
    Apply --> Tasks & Evidence
    Apply -->|"tool call"| Search --> Browser --> Adapters --> Evidence
    Tasks & Evidence --> Signals --> Budget
    Budget -->|"continue"| Select
    Budget -->|"terminate"| Assembly
    Similar -.->|"PPR expansion"| Context

Documentation Structure¶

This documentation follows a learning-curve progression --- broad concepts first, then progressively deeper into each subsystem:

Design Principles¶

Three-layer separation. LLM, orchestrator, and I/O adapters occupy distinct code layers with enforced import boundaries. The LLM never sees budget numbers; the orchestrator never generates text.

Substrate-projection architecture. Neo4j holds the complete graph (substrate). Each iteration sees only a knapsack-selected subgraph (projection) materialized into the context window.

Smooth algebra over hard logic. Budget pressure, convergence, and termination use continuous \(C^{\infty}\) functions --- soft_gate, budget_horizon, clamp01 --- rather than if-statements with magic thresholds. Behavior degrades gracefully rather than switching abruptly.

Depth over breadth. Following Ousterhout's depth-as-leverage principle, Lethe consolidates complexity behind narrow interfaces: the embedding algebra hides behind compute_iteration_signals(), Neo4j access goes through one store module, and context composition is one pipeline. Each module absorbs complexity rather than distributing it across callers.

Technology Stack¶

Algorithms and Techniques¶

The system draws from several areas of computer science and applied mathematics:

Graph algorithms --- Personalized PageRank with cosine-weighted transitions for context expansion (Page et al., 1998; Klicpera et al., 2019). DAG task decomposition with cycle detection. SIMILAR_TO edge synchronization as a sparse semantic nearest-neighbor index.

Submodular optimization --- Greedy submodular knapsack with incremental Marginal Information Gain for context packing (Lin and Bilmes, NAACL 2010). AdaGReS adaptive redundancy penalty. Maximal Marginal Relevance for final answer section ordering (Carbonell and Goldstein, 1998).

Spectral methods --- Truncated SVD on evidence embedding matrices. Eigengap as a convergence predictor. Grassmannian chordal distance for subspace tracking (Ramirez et al., 2024). Geodesic warp on the unit hypersphere for budget-driven exploration-to-exploitation transition.

Information foraging --- Embedding-based relevance scoring for URL discovery ranking (inspired by Pirolli and Card, 1999). Spectral convergence for optimal stopping. Submodular coverage tracking for evidence diversity.

Smooth control --- \(C^{\infty}\) primitives replacing all boolean gates: sigmoid soft_gate, exponential budget_horizon, clamp01. Confidence-weighted EMA trackers for cold-start-free temporal signals.

Quick Start¶

git clone https://github.com/bartosz-nowak/lethe.git
cd lethe
cp .env.example .env          # configure Neo4j credentials, model paths
docker compose up -d          # starts all 9 services (~24 GB VRAM)

Once services are healthy, send a query via any HTTP client:

curl -N -X POST http://localhost:8000/v1/responses \
  -H "Content-Type: application/json" \
  -d '{"model": "lethe", "stream": true, "background": true,
       "input": [{"role": "user", "content": "Your question here"}],
       "session_id": "my-session"}'

The first user message becomes the goal; the system message (if present) provides formatting instructions injected only during final answer assembly. See Deployment for GPU requirements, model setup, and the full environment variable reference.

License¶

Lethe is released under the AGPL-3.0-or-later license.