Skip to content

architecture.md

Latest commit

 

History

History
32 lines (22 loc) · 2.34 KB

architecture.md

File metadata and controls

32 lines (22 loc) · 2.34 KB
Raw

Architecture

Historian is a local event, transcript, and operational-history service for small agent applications. Apps emit registered structured events over HTTP. Agents ask evidence-bounded natural-language questions over A2A.

Historian preserves raw provenance underneath every derived view. Literal user messages, assistant messages, and private runtime/sidecar events are distinct record types. A runtime may render an internal event as a user-shaped /chat/completions message, but Historian never rewrites it as something the user literally said.

Design Principles

  • Python 3.12, FastAPI, SQLite WAL, JSON Schema Draft 2020-12, and a2a-sdk.
  • Opaque bearer tokens generated by the CLI and stored only as SHA-256 hashes.
  • Scopes are capability gates, not data partitions. A token with events:read or query:nlp can read or query records from all registered applications, not just its own. This is intentional: a centralized consumer (an agent, dashboard, or operator) holds one credential and queries across every app's history. Ingestion, by contrast, is source-scoped — an event's source must descend from app://{app_id} so a producer can only emit its own records.
  • Registered schemas are immutable by (app_id, event_type, version).
  • Retrieval uses timestamps, app/type/family filters, exact schema fields, literal words or phrases, and candidate- and time-bounded regex.
  • There are no embeddings, vectors, semantic indexes, or semantic-search fallbacks.
  • The local model emits structured search controls. Historian validates them and builds parameterized SQL.

NLP Query Pipeline

NLP queries merge and deduplicate all planned searches before applying the planner's global ordering and limit. max_records_per_model_call defaults to 50, max_query_records defaults to 1000, and max_evidence_characters is a secondary per-call chunk boundary. max_search_results continues to govern raw event-search APIs.

Record Families and Core Schemas

Built-in shared core.* schemas cover:

  • literal user and assistant transcript messages
  • private runtime/sidecar events
  • conversation summaries
  • durable user facts
  • application preferences
  • operational errors and status

Historian v1 stores and queries summaries, facts, and preferences supplied by authorized applications. Automatic summarization and extraction are intentionally deferred.