Architecture — Logician

01 — Package map

Seven packages, one process

Everything runs locally in a single Node process. No services to orchestrate — packages are TypeScript workspaces, not network boundaries. Four of them — log-autoresearch, log-eoh, log-memory, and log-rag — live together under packages/, one folder per capability package.

Logician architecture: seven TypeScript packages in one Node.js process, four of them under packages, a detailed log-core harness loop, and a gated tool bus connecting external systems.

02 — Dependency shape

A fan-in, not a stack

Package dependencies converge on log-runtime, which is the only package that depends on every other feature package. log-core is the single dependency-free foundation underneath it:

tui

log-runtime

blocks/log-autoresearch

blocks/log-eoh

blocks/log-memory

blocks/log-rag

log-core

log-core is the sole foundation — zero dependencies on anything else in the workspace. It's the loop, harness, hooks, compaction, and tool registry, and now also carries the versioned client protocol (system/types/types-protocol) that every runtime and client speaks, since log-protocol merged into it.
packages/log-autoresearch and packages/log-eoh each depend only on log-core, to drive their own experiment/evolution loops.
packages/log-memory, packages/log-rag, and log-eval stand alone — no internal @logician/* dependencies of their own.
log-runtime is the composition point: it depends on log-core and all four packages/* packages (log-autoresearch, log-eoh, log-memory, log-rag), and hosts every optional capability (reasoning, delegation, tasks, ask, RAG tools, and more) as one folder each under capabilities/.
tui sits on top of everything it needs directly: log-core, log-runtime, blocks/log-autoresearch, and blocks/log-memory — reaching blocks/log-rag and blocks/log-eoh indirectly through log-runtime.

03 — Package detail

What each package owns

@logician/log-core

Lean agent engine: loop, harness, hooks, compaction, tool registry — plus the versioned client protocol, since log-protocol merged into this package. Zero internal dependencies — the sole foundation.

runtime/harness and runtime/execution drive the turn loop: intake → model call → tool execution → hooks → next turn.
runtime/hooks — pre/post-tool hook chains, budget tracking, hook metrics.
runtime/compaction — context compaction, run checkpoints, and recovery when a session approaches its token budget.
capabilities/session — the append-only thread ledger, file checkpoints, and cloud-sync exclusion markers.
capabilities/tools — permissions, tool-call parsing, the tool registry.
control/ — guards and policy that enforce the loop; system/types holds the pure vocabulary (budgets, task ledger, acceptance config) both sides share without a circular dependency.
system/types/types-protocol — the versioned, UI-ready notification envelopes every runtime and client speaks; internal provider, hook, and tool events are translated before crossing this seam.
Backend abstraction over any OpenAI-compatible API, with typed, retryable errors.

@logician/log-runtime

Composes log-core into a running agent and hosts every optional capability, one folder per capability under capabilities/. The only package that depends on every other feature package, including all four under packages/.

capabilities/reasoning/ — SSR, Tree of Thoughts, Graph of Thoughts, Reflexion, Best-of-N, Self-Consistency, Auto-CoT, In-Context CoT, plus a shared base and registry.
capabilities/delegation/ — subagent spawning and definitions.
capabilities/tasks/ — todo tracking with status transitions.
capabilities/ask/ — structured prompts back to the user mid-turn.
capabilities/rag/ — retrieval-backed tools, the one place this package depends on @logician/log-rag.
capabilities/tools/ — the built-in tool registry, assembling tools from every capability above.
capabilities/memory/, lsp/, mcp/, skills/, interactions/, extensions/ — the remaining capability seams.
runtime/ — the orchestration layer on top: agent bridge, tool router, session/transcript handling, configuration.
Wires in @logician/log-eoh as one more opt-in capability.

@logician/log-eoh (packages/log-eoh)

Evolution of Heuristics (arXiv 2401.02051) — a standalone evolutionary optimization engine.

Population management, evaluator, and compaction for evolving heuristics across generations.
Own session logic, persistence, and dashboard.
Depends only on log-core; wired in by log-runtime as one more capability. Opt-in, not on the critical path.

@logician/log-autoresearch (packages/log-autoresearch)

Measured experiment loops: run, evaluate, keep or discard against a baseline.

Depends only on log-core to drive experiment trials.
Ported from pi-autoresearch; used for reproducible improvement loops rather than one-off runs.

@logician/log-memory (packages/log-memory)

Persistent, SQLite-backed memory. Stands alone — no internal @logician/* dependencies.

Observation capture, consolidation, and lexical + semantic retrieval.
Context injection back into the agent loop.
Exposed to any MCP client via @logician/log-memory-mcp (apps/log-memory-mcp), independent of the TUI.

@logician/log-rag (packages/log-rag)

Hybrid retrieval. Stands alone — consumed by log-runtime, not the other way around.

Dense + BM25 hybrid search with structural chunking and cross-encoder reranking.
Query rewriting, source attribution, and context budgeting.

@logician/log-eval

Outcome-grounded evaluation runner for agent trials. Stands alone.

Treats repository state and executable checks as authoritative.
An agent's own completion claim is retained only as diagnostic evidence, never as the pass/fail signal.

@logician/tui (apps/tui)

The terminal UI. Streams model output, tool traces, and reasoning live to any VT100-compatible terminal — local, SSH, or tmux. Depends directly on log-core, log-runtime, blocks/log-autoresearch, and blocks/log-memory.

layers/presentation — rendering pipeline.
layers/input — keybindings, input bar, steering queue.
layers/theme — theme system, theme selector.
layers/events / layers/core — event plumbing, TUI core state machine.
components/ — status bar, transcript display, MCP manager, reasoner selector, EOH panel, popups/overlays.
Entry point handles exec and doctor CLI modes before booting the interactive TUI.

04 — The turn loop

Inside the harness

Every turn moves through the same pipeline, whether it's a plain chat message, a tool call, or a subagent delegating back to its parent.

Logician log-core harness detail: task-scoped initialization; steering and follow-up queues; context transformation; provider request, payload, and response hooks; streaming model generation with retry and compaction recovery; ordered tool batches with per-call permissions and hooks; context accounting; continuation, acceptance, reflection, and structured run outcomes.

Task scope and intake — initializes the registry, result cache, system prompt, and task status, then drains steering at turn boundaries and follow-ups when the agent would otherwise become idle.
Provider pipeline — context transforms run before transport conversion; request and payload hooks can modify provider options, and thinking, text, and tool-call deltas stream as ordered events.
Recovery and compaction — retryable provider failures use bounded retry; context-full failures compact to a target budget and retry. Proactive compaction also runs while preparing a later turn.
Tool batches — each call is prepared and permission-checked before internal and user hooks run. Parallel-safe calls execute concurrently around sequential barriers, while result messages retain the model's original order.
Loop or finish — context accounting, diagnostics, refreshed configuration, and queued messages can continue the loop. Stop policies, acceptance verification, optional reflection, and structured task status determine the final run outcome.

05 — Outside the process

The tool bus

Everything the agent can touch outside its own process goes through a typed tool call — visible, loggable, and gated by the permission mode.

LLM backend

Any OpenAI-compatible API — local (llama.cpp) or hosted, swappable with a single config change.

MCP servers

stdio and streamable-HTTP transports via log-runtime/capabilities/mcp.

SearXNG

web_search / web_fetch against a local or remote SearXNG instance.

Filesystem · Git

bash, ripgrep-backed grep, fd/find-backed find, and git status/diff/log.