Gradatum · Agent Layer

Foundations first.
Runtime next.

Two of the three layers that make a self-hosted agent stack are already in place. The memory store and the compute backbone are live — sovereign, embedded, no SaaS round-trip. At v1.0.0 the agent layer reached production form: the engine and gateway are formalised install components, the full stack ships in Docker, and multi-tenant isolation is hardened on the production queue path. The agent runtime that orchestrates them is planned for v2.0.

Memory + Compute live Agent Layer formalised · v1.0.0 Runtime · v2.0

Live since v0.3.0 · formalised v1.0.0
Planned · v2.0

Live since v0.3.0 · formalised at v1.0.0

Two foundations.
Already in place.

The runtime planned for v2.0 builds on two live components — a compute layer for inference routing, and a memory layer for persistent knowledge. Both are sovereign, embedded, and running today. Since v1.0.0 the agent layer ships in production form: the engine and gateway are formalised install components (--with-engine / --with-gateway), the six-binary stack deploys through Docker, and multi-tenant isolation is hardened on the production queue path (stale-lease recovery, JWT iss/sub, tenant-scoped revocation).

LIVE Compute
Gateway — unified LLM router

Gateway

Context

OpenAI-compatible Chat Completions — multi-turn, multimodal content (text + base64 images), tool-calling, SSE streaming. Semantic reranking and embeddings as native endpoints.

Routing & fallback

Each model alias maps to a primary backend with an optional configurable fallback. A per-provider circuit-breaker (closed / open / half-open) trips on transient errors, and a smart router applies per-context defaults or header-driven overrides.

Logs

Every LLM call is recorded in an append-only journal — alias, effective provider, route, latency, tokens, HTTP code, role id — with 30-day retention, a 5M-event cap, and Prometheus export. Conversation content is never captured.

Identity

Endpoints are guarded by Bearer token with constant-time comparison and an optional loopback bypass keyed on the real TCP address. Business-context ids (feature, agent) are propagated into telemetry — never exposed in logs.

Engine fleet — local inference

Engine fleet

Optimization

A native Rust supervisor runs inference processes directly — managing GPU, context window, slot parallelism and sampling per model instance, under strict execution-environment isolation and graceful shutdown.

Monitoring

Each inference instance exposes a real-time health endpoint (starting / ok / unhealthy) and Prometheus metrics (requests, latencies), with automatic supervision under a bounded restart budget and flapping detection.

Shared config & logs

Per-instance configuration is declarative TOML with environment overrides. Every request emits an async, non-blocking telemetry event (route, model, latency, HTTP code, role id) to the central journal — engine and server share the same core types and auth handshake.

LIVE Memory

Vault

Sovereign knowledge store — BM25 + cosine + RRF, MCP, history, temporal index.


Chapter II

Agent Layer

A store that answers queries on demand is still passive. The real value is a system that knows what is relevant before you ask — one that remembers what you worked on yesterday, surfaces the decision you forgot last month, and assembles exactly the right context before sending anything to a model. Everything built in Chapter I exists to make this layer possible.

v0.7.0 shipped

Memory Layer + Context Assembly

A store that answers queries on demand is still passive. The real value is a system that knows what is relevant before you ask — one that remembers what you worked on yesterday, surfaces the decision you forgot last month, and assembles exactly the right context before sending anything to a model. v0.7.0 is that layer: gradatum stops treating each session as stateless and starts reasoning over everything it has accumulated, on your hardware, across time.

  • Assembles relevant context before each query — not raw retrieval
  • Memory window slides with the conversation — no context cliff
  • Proactively surfaces what you forgot you knew
  • Declarative user profile — gradatum knows who it is talking to
  • Picks only the skills relevant to the current task
v0.8.0 in progress

Vault Stability — Reversible Deletion & Hygiene

Deleting a note used to mean losing it. v0.8.0 turns on-demand delete into an archival operation: the note's Markdown and its history move under an archive tree, a durable JSONL tombstone is written before the cascade, and the note stays recoverable until a configurable 60-day retention deadline, after which a registry-driven GC destroys it. Restoring re-indexes the note as pending-review, so it re-enters the curator instead of going straight back to live. The whole archive lifecycle sits behind an operator-only CLI on a loopback admin namespace — agents can list archives over MCP but never delete, restore, or purge. The same train is set to add an opt-in vault audit and deduplication job, curator threshold tuning, and qualified method-call resolution in the code index — still planned within the v0.8.0 line.

  • On-demand delete archives the note instead of destroying it — recoverable for the retention window
  • A durable JSONL audit tombstone is written before any cascade
  • Registry-driven GC destroys archives past their 60-day, configurable deadline
  • Restore re-enters the curator as pending-review, never straight back to live
  • Archive lifecycle is operator-only — MCP can list archives, never mutate them
  • Opt-in vault audit and deduplication job, curator tuning, and code-map resolution still planned
v1.0.0 in progress

Production Baseline

API stability is a promise, not a feature. v1.0.0 is the version where gradatum makes that promise: the public contracts freeze, semver guarantees kick in, and anything built on top will not break without explicit notice. The Agent Layer reaches production form: gradatum-engine is a formalised install component (--with-engine / --with-gateway), the gateway routes all inference behind one alias, and the full six-binary stack deploys through Docker with network isolation. Multi-tenant isolation is hardened on the production queue path — stale-lease recovery, JWT iss/sub validation, tenant-scoped revocation — proven over 30 days of continuous operation with per-identity access scopes.

  • API contracts frozen — safe to build on without breaking changes
  • 30 days of continuous production operation proven
  • Long-term memory benchmark reproduced and published
  • Multi-user access with per-identity scopes
  • Engine formalised as an install component (--with-engine / --with-gateway)
  • Multi-tenant isolation hardened on the production queue path
  • Full stack via Docker — six binaries, network isolation
v2.0.0 planned

Multimodal, Consolidation & Sovereign Agent Runtime

Text was always just the starting point. v2.0.0 extends gradatum to images, audio, and documents — and introduces long-horizon memory consolidation, where the system compresses and learns from its own history over time. This version also ships gradatum-code: a terminal agent that reasons over your codebase using vault memory, recalls past decisions, and executes tasks end-to-end on local hardware — nothing leaves your machine. This is a breaking change by design: the chat API is rebuilt to handle multimodal input natively, completing gradatum's arc from a local knowledge store to a full cognitive infrastructure.

  • Images, audio, and documents understood alongside text
  • Long-horizon memory consolidation — the system learns from its own history
  • Sovereign terminal agent — reasons over your codebase and executes tasks end-to-end
  • Runs entirely on local hardware — nothing leaves your machine