Skip to main content
Version: 0.4.0

Architecture

The agent​

At the core of the service is The Brain: a single Deep Agent built with createDeepAgent (src/agents/agent.ts), which returns a compiled LangGraph graph. It replaces the supervisor-plus-specialists graph of earlier releases — instead of routing between four hand-written nodes, one persona-driven agent guides the user through a topic, and either teaches it or writes an article about it.

  • Persona and journey (src/agents/persona.ts, src/agents/prompts.ts) define who The Brain is and the conversation's state machine.
  • Tools (src/agents/tools.ts) supply everything factual: list_topics, list_subtopics, retrieve_content (BM25 fused with vector similarity over src/storage/knowledge-store.json — see Retrieval), and the article file tools.

See Agent Flow for the journey diagram and the design rationale.

State​

Defined in src/agents/types.ts:

  • messages: the LangChain message history for the thread.
  • todos / files: the Deep Agents planning and virtual-filesystem state.
  • instructorState: backward-compatible output shape (userQuestion, explanation) consumed by every entrypoint's response formatting. explanation carries only the latest reply, since the checkpointer accumulates the full thread.

runGraphWorkflow() in src/agents/graph.ts keeps its original signature, so the CLI, REST, MCP and ACP entrypoints are unaffected by the agent's internals.

Persistence layer​

  • SQLiteCheckpointer (src/storage/sqlite.ts) extends LangGraph's BaseCheckpointSaver to persist thread history locally inside state.db. It applies PRAGMA journal_mode = WAL, synchronous = OFF, and temp_store = MEMORY for performance, and creates the database directory if it does not already exist. This checkpointer is used by every entrypoint, in every environment.
  • S3Wrapper (src/storage/s3.ts) is used by higher-level cloud state storage. It lets the AWS SDK's default credential chain resolve (env vars, shared config, SSO/AWS_PROFILE, a container/instance role) and transparently falls back to an in-memory Map when none are present, so local development never requires AWS access. The deployed Lightsail container service currently has no runtime IAM role either, so production runs on this same fallback (see Infrastructure).
  • Knowledge store (src/storage/knowledge-store.json) is a pre-compiled, paragraph-level chunk database (5,166 chunks, ~2.4MB) generated by src/scripts/ingest.ts, tagged by area, carrying each chunk's content-addressed id, source file and heading, and loaded lazily/cached in memory by src/agents/tools.ts.
  • Embeddings (src/storage/embeddings.bin) hold one quantised 256-dimension vector per chunk (~1.3MB), built during ingest when a Gemini key is present. Optional by design: without them retrieval runs on BM25 alone. Both files are gitignored and reach the container through COPY src/ — see Retrieval.

Data flow (REST example)​

For LLM provider selection, see createChatModel() in Source Code Reference.