Skip to main content

Technical stack

The product architecture is implemented as a persistence-first runtime with explicit durable owners, rebuildable retrieval, and request-time context assembly.

This page summarizes the active technical direction behind that model.

Design goals​

The clean-slate stack is optimized for:

  • persistence-first runtime behavior with explicit durable owners
  • fewer package boundaries that map directly to the accepted architecture
  • request-time context assembly with a stable prompt envelope
  • rebuildable retrieval indexes and summaries
  • cutover paths that delete overlap instead of preserving it forever

It explicitly tries to avoid:

  • compatibility shims that keep legacy owners alive
  • mirrored writes between old and new packages
  • hidden prompt-owned state
  • a second memory or learning store outside the canonical evidence path
  • provider-specific indexing logic leaking into product modules

Core runtime stack​

Runtime and contracts​

  • Python 3.12+
  • pyproject.toml plus uv for project metadata and dependency management
  • pydantic v2 for configuration models and internal contracts
  • standard-library logging first, with typed telemetry events

Persistence and retrieval​

  • SQLite as the primary structured store
  • SQLAlchemy 2 and Alembic for migrations
  • SQLite FTS5 for lexical retrieval
  • mmbert-embed-32k-2d-matryoshka as the vector retrieval backbone
  • optional sidecar indexes only when they remain rebuildable from canonical evidence rows

Recommended mmbert modes:

  • 64d for broad low-cost candidate generation
  • 256d for default online recall
  • 768d for rebuild, replay, and difficult recovery evaluation

Interfaces and surfaces​

  • Typer for the CLI command surface
  • prompt_toolkit plus Rich for the direct shell
  • FastAPI plus uvicorn for the API server
  • in-process background scheduling first, external workers only when the learning loop and verification queues prove they are needed

Package topology​

The long-term package cut should mirror the architecture more directly. The target shape is:

  • packages/runtime for one-turn orchestration and wake execution
  • packages/state for ProfileGraph and WorkGraph
  • packages/evidence for evidence formation, retrieval, and governance
  • packages/context for SessionFrame construction and prompt assembly
  • packages/learning for clustering, verification, and procedure promotion
  • packages/skills for skill packaging and overlays
  • packages/capabilities for tools, providers, auth, and adapters
  • packages/operator for inspect and patch surfaces
  • packages/storage, packages/session, packages/security, packages/telemetry, and packages/contracts for shared infrastructure

Cutover direction​

The technical design also defines where older package boundaries should land over time:

  • packages/profile folds into packages/state
  • packages/planning folds into packages/state or packages/runtime
  • packages/memory folds into packages/evidence
  • packages/experience is replaced by packages/learning
  • prompt-era write helpers should move into packages/operator or be deleted when they only exist to compensate for missing runtime-owned persistence

The core rule is simple: when a clean-slate package becomes authoritative, delete the legacy overlap instead of mirroring it forever.

Validation shape​

The technical design assumes validation across several layers:

  • repository-native unit, integration, end-to-end, and scenario tests
  • lint and formatting checks
  • static typing
  • replay and recovery evaluation for difficult continuity paths
  • release and contract validation in CI

One important reality check​

The design stack sketches a broader future for operator-facing web surfaces, but the currently shipped public docs site in this repository is still a static Docusaurus app.

That is intentional here:

  • this page summarizes the runtime target architecture
  • the public site remains a lightweight documentation shell
  • future richer operator surfaces should be judged against the same durable-owner model rather than treated as a second source of truth

Where to go next​

For a messaging-facing extension of the same runtime, continue with Gateway and messaging adapters.