How one user message travels through reflect.
User prompt (TUI or reflect exec)
β
βΌ
βββββββββββββββββββββ
β buildSystemPrompt β AGENTS.md + prompt templates (practices.md)
βββββββββββ¬ββββββββββ
β
βΌ
βββββββββββββββββββββ βββββββββββββββ
β local memory βββββββ ~/.reflect/ β conventions, decisions, lessons
β recall β β memories β
βββββββββββ¬ββββββββββ βββββββββββββββ
β
βΌ
βββββββββββββββββββββ βββββββββββββββ
β token budget β β embedded β CountTokens, CompressForContext
β (context sizing) β β library β
βββββββββββ¬ββββββββββ βββββββββββββββ
β
βΌ
βββββββββββββββββββββ βββββββββββββββ
β Reflect ChatClient ββββββΊβ relay/engineβ catalog, credentials, routing
β port + adapter β β generate/ ββββββΊ provider API
βββββββββββ¬ββββββββββ β stream β
βββββββββββββββ
β
βΌ
Tool calls (Read, Edit, Bash, β¦)
β
βΌ
Response to user
β
βΌ (when context grows)
βββββββββββββββββββββ
β token Compress β fast path before LLM summarization
β + relay compact β
βββββββββββββββββββββ
- relay: The Reflect composition root creates an
relay/engine.Enginewith Relay-owned state paths, an injected secret store, and per-engine custom gateway metadata. The engine loads provider state and the model catalog, then builds transport behind Reflect'sChatClientport. - memory:
configureSessioninitializes the local memory manager (core, auto, evolving, zen, retrieval metrics, continuity). If the state directory is unavailable, reflect runs without persistent memory. - token: No startup step β embedded at compile time.
- Reflect templates (
internal/prompts/templates/*.md) define behavior, tools, and practices. - Project
AGENTS.mdis appended viareflectconfig.BuildContextWithDirs. - memory:
Memory.Recallinjects relevant stored memories into the system prompt.
Each turn:
- memory β recall memories matching the latest user message (token budget ~2000).
- relay β Reflect's adapter calls engine generate/stream with Reflect-owned tool definitions; Relay normalizes provider events and tool requests.
- Tools run with the session's memory service in context.
- memory β post-session bookkeeping records the session goal and outcome.
When messages exceed limits (internal/engine/compact.go):
- token β
token.Compress()tries a fast compression path for summaries. - relay β if token reduction is insufficient, reflect calls the LLM to summarize, then keeps recent messages.
internal/engine/token/tokenizer.gowraps the embedded token engine for precise and fast estimates used in budget UI and compaction decisions.
reflect doctor # ecosystem panel + relay preflight
./scripts/smoke-reflect.sh # build + quick tests| Module | Role in reflect | Required? |
|---|---|---|
| relay | LLM APIs, catalog, credentials, routing | Yes |
| internal/token | Token estimate + context compression + secrets + usage | Yes (embedded, no config) |
relay is independently published and pinned in Reflect's go.mod. Optional
coordinated development uses a gitignored go.local.mod with a local Relay
replacement. Reflect never generates a parent workspace.
Production Reflect code imports Relay only through relay/engine. Conversation
history, WAL/resume, permissions, tool execution, and memory remain in Reflect;
provider credentials, discovery, selection, transport, resilience, and
normalized streaming remain in Relay.