Skip to content

Latest commit

Β 

History

History
109 lines (87 loc) Β· 4.66 KB

ecosystem-message-flow.md

File metadata and controls

109 lines (87 loc) Β· 4.66 KB

Message flow (relay + embedded token engine)

How one user message travels through reflect.

Overview

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   β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Step by step

1. Session start (reflect or reflect exec)

  • relay: The Reflect composition root creates an relay/engine.Engine with 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's ChatClient port.
  • memory: configureSession initializes 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.

2. System prompt assembly

  • Reflect templates (internal/prompts/templates/*.md) define behavior, tools, and practices.
  • Project AGENTS.md is appended via reflectconfig.BuildContextWithDirs.
  • memory: Memory.Recall injects relevant stored memories into the system prompt.

3. User message β†’ agent loop (internal/engine/stream.go)

Each turn:

  1. memory β€” recall memories matching the latest user message (token budget ~2000).
  2. relay β€” Reflect's adapter calls engine generate/stream with Reflect-owned tool definitions; Relay normalizes provider events and tool requests.
  3. Tools run with the session's memory service in context.
  4. memory β€” post-session bookkeeping records the session goal and outcome.

4. Context pressure

When messages exceed limits (internal/engine/compact.go):

  1. token β€” token.Compress() tries a fast compression path for summaries.
  2. relay β€” if token reduction is insufficient, reflect calls the LLM to summarize, then keeps recent messages.

5. Token accounting

  • internal/engine/token/tokenizer.go wraps the embedded token engine for precise and fast estimates used in budget UI and compaction decisions.

Verify locally

reflect doctor              # ecosystem panel + relay preflight
./scripts/smoke-reflect.sh  # build + quick tests

Module layout

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.