Gradatum Vault · cognitive memory backbone for AI agents

A place of
memory for
your agents.

Gradatum is a self-hosted, embedded memory backbone for multi-agent AI systems. It cures memory rot in LLMs and lets Claude, Gemini, Codex and your home-grown agents share what they know — across sessions, across machines, across runs.

GitHub crates.io Read the architecture

« Loci sunt, in quibus imagines collocantur. »

Cicero · de Oratore II — the loci are the places where images are set down.
I · The problem

LLMs forget. Agents reinvent the wheel every session. Teams of agents can't share what they learn.

What's missing today
  • SaaS lock-in — your memory hosted on someone else's server
  • Heavy stacks — Postgres + pgvector + Neo4j just to remember things
  • Built for humans, not agents — no ACL, no multi-tenancy, no MCP
  • Transient context, not persistent KB — forgets between sessions
What Gradatum does

One Rust binary. SQLite + Markdown on disk. No PostgreSQL. No Redis. No SaaS. Pluggable LLM (or none). Multi-vault. Hierarchical ACL. Hybrid search — BM25 (SQLite FTS5) + semantic (cosine) + PageRank. The Markdown files are the source of truth — not the index.

II · Properties

The Gradatum approach

Embedded One Rust binary. No PostgreSQL. No Redis. No external services. apt install and you're running.
Self-hosted Your memory, your machine. No telemetry. No vendor lock-in.
LLM-agnostic Plug any OpenAI-compatible backend (Ollama, vLLM, llama.cpp, OpenRouter, Anthropic) — or run heuristic-only with no LLM at all.
Multi-vault Separate main from staging and bench-* vaults for testing, migration, A/B prompts. Atomic swap when ready.
Hierarchical ACL Bearer-scoped access to memory loci. Configure from presets (flat, hierarchical, multi-project, team) or write your own.
Multi-storage OpenDAL abstraction — Local filesystem available. S3/R2, Azure, GCS planned (feature flags available; backend implementations pending). NFS explicitly rejected.
Markdown truth Notes are Markdown files with YAML frontmatter. Readable by humans and by cat. The database is an index, not the source of truth.
Hybrid search BM25 (SQLite FTS5) + semantic search (cosine brute-force; ANN (sqlite-vec) optional). PageRank graph + reranker abstraction (no-op by default; cross-encoder ONNX optional). Multi-signal fusion via RRF (Reciprocal Rank Fusion).
III · Architecture

One binary. Four planes. Markdown on disk.

A stateless façade speaks HTTP and MCP to your agents. A worker drains a SQLite-backed queue. One vault per instance is the default — staging and bench-* vaults are first-class for migration and A/B testing. 

        AI agents · coding assistants · orchestrators
              ↓  MCP / HTTP / CLI  (RFC-0003: :19090)
        ┌─────────────────────────────────────────┐
        │  gradatum-server                        │  stateless façade
        │  /api/v1  /mcp  /sse  /health  /admin  │
        └────────────────┬────────────────────────┘
                         ↓  async queue · Apalis (SQLite, lease 5min)
        ┌─────────────────────────────────────────┐
        │  gradatum-worker                        │  curator + maintenance
        └────────────────┬────────────────────────┘
                         ↓  DATA PLANE (19 of 28 product crates)
        ┌─────────────────────────────────────────┐
        │  core  markdown  vault  storage  index  │
        │  search  queue  cache  chat  curator     │
        │  embed  engine  acl-policy  acl-auth     │
        │  auth  dto  db-sqlite  warden  gateway  │
        │  [SQLite FTS5 · cosine · reranker (no-op)  │
        │   Apalis · OpenDAL · llama.cpp · rmcp]  │
        └────────────────┬────────────────────────┘
                         ↓  CLIENTS
        ┌─────────────────────────────────────────┐
        │  gradatum-mcp-stub  (stdio→HTTP proxy)  │
        │  gradatum CLI                           │
        │  gradatum-sdk-rs                        │
        │  gradatum  (umbrella SDK facade)        │
        └─────────────────────────────────────────┘
Lifecycle of a note

How a note lives.

A note in Gradatum follows two pipelines: one when it's written (ingested + understood + indexed), one when it's searched back. Both run on the same machine, in milliseconds, with zero SaaS round-trip.

✎

Write

an agent submits a note
  1. 1

    Authenticate the agent

    The agent presents an API key. Gradatum exchanges it for a short-lived JWT used for the rest of the session.

    api-key (chmod 600) · POST /auth/exchange · JWT 24 h

  2. 2

    Accept and queue

    The note is queued. The call returns immediately — the agent doesn't wait for indexing.

    POST /api/v1/vault_write · 202 Accepted

  3. 3

    Curate (or skip)

    A local LLM classifies the note into a canonical section. Skipped when the agent already provides one.

    Qwen3-4B local · skipped when section_hint set

  4. 4

    Extract the title

    If the note starts with a heading, that becomes the title — a stable identifier for cross-references.

    H1 markdown extract · stored in notes.title

  5. 5

    Compute meaning (embedding)

    The text is turned into a numeric fingerprint of its meaning. Two notes on the same topic land near each other — even with no shared words.

    bge-m3 · 1024-dim vector · local inference

  6. 6

    Connect the dots (wikilinks)

    Cross-references inside the note become edges in the vault's graph. Backlinks build naturally over time.

    B5 post-curate · [[Note]] → graph table note_links

  7. 7

    Persist everything

    Text, vector, full-text index, graph edges — all written in a single atomic transaction.

    SQLite WAL · FTS5 · BLOB f32 · ULID keys

  8. ✓

    Ready to be recalled

    The note is live and searchable.

    end-to-end ~0.5–2 s · dominated by embedding

⌕

Search

an agent asks a question
  1. 1

    Reuse the auth

    The JWT is refreshed automatically when it nears expiry. Most search calls pay no auth cost.

    auto-refresh · under 30 % TTL remaining

  2. 2

    Receive the query

    The agent sends a natural-language query and optional filters.

    POST /api/v1/vault_search · section, tenant, limit, include_downgraded

  3. 3

    Search by words

    Classic full-text search returns notes containing the query terms. Fast and exact — blind to synonyms.

    SQLite FTS5 · BM25 ranking

  4. 4

    Search by meaning

    The query is matched against note fingerprints by similarity. Returns notes that mean the same thing — even with no shared words.

    bge-m3 query embed · cosine similarity in-process

  5. 5

    Reconcile both rankings

    The two ranked lists are merged into one — without needing to calibrate scores between them.

    Reciprocal Rank Fusion · k = 60 · stable sort

  6. 6

    Boost by context

    Recent notes get a small bump. Notes linked to by many others get another.

    composite = rrf × (1 + α × recency) × (1 + β × pagerank) · α=0.2 β=0.1

  7. 7

    Re-rank the top results

    A neural model rescores the top candidates with deeper understanding. Off by default — opt-in.

    reranker abstraction (no-op by default) · cross-encoder ONNX optional · feature onnx-reranker

  8. 8

    Build readable snippets

    A short excerpt around the match is extracted — the agent gets context, not just an ID.

    FTS5 native snippet() · « match »

  9. ✓

    Return the top-N

    Each result carries id, score, title, snippet, section, tags.

    end-to-end ~50–200 ms (no reranker) · ~150–400 ms (with)

Write — local, queued, asynchronous · Search — synchronous, milliseconds · Everything runs on one box. No cloud round-trip.
IV · Vocabulary

Six levels, named with care.

Borrowed from Cicero's ars memoriae: agents place their memories in loci, mental locations of an imagined palace. Agents don't share rooms — they share places of memory.

Vault
The technical backing store (SQLite FTS5 + Markdown). Multi-vault first-class — main + staging + bench-*.
Locus
A logical subdivision of a vault, isolated by ACL. From Cicero's ars memoriae — the mental location where an image is placed.
Section
One of 10 cognitive categories: decisions, architecture, debug, reasoning, feedback, lessons-learned, retrospectives, experiments, agent-issues, reference.
Note
Atomic Markdown file with YAML frontmatter. ULID identity. SHA-256 content hash for drift detection.
Bearer
An authenticated identity with read/write ACL patterns over loci. Configured via presets or custom bearer.toml.
Preset
A template configuration shipped in examples/presets/ — flat, hierarchical, multi-project, team.
V · Multi-storage

One backend today. More planned.

Gradatum uses Apache OpenDAL as a unified storage abstraction layer. Local filesystem is available today; S3, Azure, and GCS support is planned. NFS is explicitly rejected: POSIX lock incompatibility causes data corruption under concurrent writers.

  • Local FS primary
    fs://

    Default. NVMe local only — NFS rejected: POSIX lock incompatibility causes data corruption under concurrent writers.

  • S3 / R2 planned
    s3://

    AWS S3, Cloudflare R2, MinIO, Backblaze B2. Feature flag available; backend implementation pending.

  • Azure Blob planned
    azblob://

    Azure Blob Storage via OpenDAL azblob service. Feature flag available; backend implementation pending.

  • GCS planned
    gcs://

    Google Cloud Storage. Service account or ADC auth. Feature flag available; backend implementation pending.

Example — gradatum.toml
# Per-vault storage configuration
[vaults.main.storage]
backend = "s3"
bucket  = "my-gradatum-vault"
region  = "us-east-1"
root    = "/gradatum/main"

[vaults.staging.storage]
backend = "fs"
root    = "~/.gradatum/vaults/staging"  # local NVMe for testing

# NFS rejected: POSIX lock incompatibility (data corruption under concurrent writers)
# backend = "nfs"  ← will fail at startup with nfs_check.rs guard
VI · Status & Roadmap

Roadmap — fifteen versions, four milestones

v1.0.0 · 31 crates workspace · Apache-2.0 · Rust 2024 · MSRV 1.88+ · GitHub · full workspace (27 crates) on crates.io — source releases; API stable since v1.0

v0.1.0 · architecture foundation

BRONZE Architecture Foundation

✓ SHIPPED

Before you can build a useful memory layer, you need a store that actually works. v0.1.0 ships a functioning knowledge base — write, read, search — accessible over HTTP and MCP from day one. It lays the structural foundations that every later version builds on: pluggable storage interfaces, note integrity guarantees, and enough test coverage to deploy with confidence.

explore shipped features →
  1. Working knowledge store — read, write, search, first deployment v0.1.0-alpha.0→5 2026-04
  2. Accessible over HTTP and MCP — any client can connect without custom integration v0.1.0-alpha.5 2026-05-07
  3. Search hardened — full-text and semantic results fused, accuracy improved v0.1.0-alpha.7→10 2026-05
  4. Dependencies updated — no known vulnerabilities in the supply chain v0.1.0-alpha.10-bumps.1 2026-05
  5. Search ranking improved — results reordered by relevance, not just keyword match v0.1.0-alpha.11→13 2026-05
  6. Migrated to gradatum as its own primary store — dog-fooding from day one v0.1.0-alpha.13 2026-05-25
  7. Auth tokens validated more strictly — future-dated tokens rejected v0.1.0-alpha.14 2026-05-28
  8. Agent skills shipped — gradatum can remind itself what it knows and search its own vault gradatum-skills v0.1.0 2026-05-25
  9. Note titles always resolve correctly — no more missing titles in search results v0.1.0-alpha.15 2026-05-28
  10. Alpha series closed — stable enough for early adopters v0.1.x closing 2026-05-29
v0.2.0 · job infrastructure + observability

BRONZE Job Infrastructure + Observability

✓ SHIPPED

Gradatum processes notes asynchronously — curation, embedding, distillation all run in the background. Without a reliable job engine, these tasks would silently fail and leave the vault in an inconsistent state. v0.2.0 ships that engine: background jobs survive restarts, failures are captured and retried rather than dropped, and every running task is visible in real time. This infrastructure is what makes every subsequent feature safe to ship.

explore shipped features →
  1. Background job engine wired — tasks run reliably in the background without blocking the API v0.2.0 2026-05-29
  2. Failed jobs captured in a dead-letter queue — nothing is silently lost, retries are configurable v0.2.0 2026-05-29
  3. Job status visible over HTTP with live push updates — operators see what is running and why v0.2.0 2026-05-29
  4. Tagged — Bronze milestone, public OSS release v0.2.0 2026-05-29

Background jobs that survive restarts · Failed jobs captured, never silently dropped · Live job status via HTTP + real-time stream

v0.3.0 · storage traits + event-log + secrets di

BRONZE Storage Traits + Event-Log + Secrets DI

✓ SHIPPED

A knowledge store that is locked to a single database is a dead end. v0.3.0 separates the document layer, the search index, and the vector store into independent, swappable components — you can replace any one of them without rewriting the rest. It also fixes a critical bug where every server restart would invalidate all live sessions, and introduces a built-in model proxy so LLM calls are routed, reranked, and fully cost-attributed without a separate service.

explore shipped features →
  1. Storage split into three independent layers — swap the database, search index, or vector store without touching the rest v0.3.0 2026-06-01
  2. Every LLM call logged with cost attribution — know exactly what each operation spent v0.3.0 2026-06-01
  3. Built-in LLM proxy and reranker — route model calls and reorder results by relevance without a separate service v0.3.0 2026-06-01
  4. Notes automatically tagged by memory type (episodic, semantic, procedural) — no LLM inference required, fully deterministic v0.3.0 2026-06-02
  5. Auth key survives server restarts — sessions no longer expire unexpectedly on reboot v0.3.0 2026-06-02
  6. Tagged — 28 crates, 1088 tests PASS, Bronze 3rd milestone v0.3.0 2026-06-02
  7. Parallel workers no longer deadlock under concurrent job load v0.3.3 2026-06-02
  8. Search results always show their title — no more blank note titles in results v0.3.4 2026-06-03
  9. Semantic search results enriched with title and excerpt — easier to scan at a glance v0.3.5 2026-06-03
  10. First public OSS release: source on GitHub, 28 crates published on crates.io (Apache-2.0) v0.3.6 2026-06-05
  11. Read and write reliability fixed: search titles persist, notes retrievable by ID, internal links reconcile correctly v0.3.7 2026-06-05

Pluggable storage (swap backend without rewriting) · Cost tracking per LLM call · Built-in LLM proxy + reranker · Notes tagged by cognitive type (episodic / semantic / procedural) · Auth key never hardcoded — injected at startup

Chapter I

Memory layer

v0.4.0 → v0.5.1 — Completes the durable memory store: note history, temporal decay, semantic forget, VaultScope addressing, distillation, and MCP-native querying. Access is authenticated with a server-issued API key; multi-user isolation and remote client access are still ahead on the roadmap. The queryable, sovereign memory store that other systems — and eventually gradatum itself — will build on.

v0.4.0 · vault core — durable memory layer

Vault Core — Durable Memory Layer

✓ SHIPPED

A store that only appends is not enough — you need to know what you can trust, recover from mistakes, and keep the vault from growing unbounded. v0.4.0 completes the memory layer: every note carries a trust score, a full edit history, and stable internal links that survive renames. Notes can be intentionally forgotten with progressive decay, and concurrent writes are always safe. This is the version that turns a write-only store into a durable, queryable memory.

explore shipped features →
  1. Every note carries a trust score based on its origin — search results rank sources you can verify higher v0.4.0 2026-06-06
  2. Internal links between notes are stable — rename a note without breaking the references that point to it v0.4.0 2026-06-06
  3. Concurrent edits are safe — two writers on the same note at once get a clear conflict error, not silent data loss v0.4.0 2026-06-06
  4. Full edit history kept for every note — restore any previous version at any time v0.4.0 2026-06-06
  5. Tagged — 28 crates, 1178 tests PASS, durable write milestone v0.4.0 2026-06-06
  6. API never panics on bad input, all public docs written, SECURITY.md published, first crates.io + GitHub release v0.4.1 2026-06-06
  7. Write response now returns the note ID, demote-note returns a clear 404 when the note does not exist v0.4.2 2026-06-07
  8. Notes can be intentionally forgotten (with a dry-run preview), history pruning is configurable, multimodal input supported in the gateway v0.4.3 2026-06-10

Stable internal links — rename a note without breaking references · Full version history — every edit preserved · Safe concurrent writes — no lost updates · Sources carry verifiable lineage · Notes can be intentionally forgotten · Chronological memory queries

v0.4.3 · addressing & query scoping — multi-vault foundation

SILVER Addressing & Query Scoping — Multi-Vault Foundation

✓ SHIPPED

Multi-vault deployments need a unified way to address data across vaults and agents without per-job coordination. v0.4.3 ships that abstraction: VaultScope gives every background job a composable, deterministic address; Semantic Forget completes the data lifecycle with intentional deletion and decay; and Temporal Index adds chronological querying so agents can reason about when events happened and in what order.

explore shipped features →

VaultScope: address any locus across vaults and agents · Semantic Forget with mandatory dry-run and progressive decay · Temporal Index with before/after/around queries

v0.5.2 · static code index + temporal queries + observability

SILVER Static Code Index + Temporal Queries + Observability

✓ SHIPPED

Memory without code awareness is half the picture. v0.5.2 adds a code index built directly from source — no LLM, no hallucination — so gradatum can answer "where is this function?" as reliably as "what was decided last week?". The index updates in milliseconds when files change, and stays in a separate store so it never pollutes the knowledge vault. A temporal index foundation enables time-aware queries: agents can reconstruct decision timelines and detect sequencing contradictions without external tools. This version also ships encrypted connections natively and makes it possible to know for certain that a topic is absent, not just unranked.

  1. Edit a note in place without creating a new version — conflicts detected automatically if two writers race v0.5.0 2026-06-12
  2. Every agent action logged for 90 days — audit what ran, when, and what it touched, without storing personal data v0.5.0 2026-06-12
  3. Search can now confirm a topic is truly absent — not just "nothing ranked high enough" v0.5.1 2026-06-13
  4. Browse notes in chronological order, filter by date range — see what was written before or after a given moment v0.5.1 2026-06-13
  5. Codebase indexed from source — find any Rust function, struct, or file by name or keyword, no LLM required v0.5.2 2026-06-13
  6. Code search by symbol, free text, or file path — optionally include the full source body in results v0.5.2 2026-06-13
  7. Index updates only what changed — re-indexing after an edit takes milliseconds, not seconds v0.5.2 2026-06-14
  8. Encrypted connections enabled natively — no reverse proxy required for TLS v0.5.2 2026-06-14
  9. Tagged — 31 crates, 1925 tests PASS, source on GitHub (Apache-2.0) v0.5.2 2026-06-15

Code index built from source — no LLM needed, zero hallucination · Search your codebase by symbol, keyword, or file path · Index stays in sync automatically — only changed files are reprocessed · Browse notes chronologically, filter by date range · Temporal queries: before/after/around/upcoming dates without a calendar database · Agent action tracing — what ran, when, and why · Know for certain if a topic exists in the vault, not just "nothing found" · Encrypted connections out of the box (TLS 1.2+/1.3) · Edit notes safely under concurrent load — conflicts detected, never silently overwritten

v0.5.5 · foundation polish

SILVER Foundation Polish

✓ SHIPPED

Before opening gradatum to external clients via MCP, the foundation needs to be verifiably clean. v0.5.5 closes that window: the health endpoint now reports the exact running version and real queue state so there is no ambiguity about what is deployed. No new user-facing features — the goal is a baseline you can audit and depend on before the next chapter begins.

Real-time health endpoint — queue depth + version proof · Codebase modernized to Rust 2024 edition · API surface cleaned and hardened before the MCP pivot

v0.6.0 · queryable memory store — mcp-native backend

SILVER Queryable Memory Store — MCP-Native Backend

✓ SHIPPED

Until now, gradatum was only usable through its own agent. v0.6.0 opens the vault to any MCP-compatible client — Claude Code, IDEs, custom agents — over a standard HTTP connection, with no sidecar process or protocol shim. The deliberate choice here: make the store useful to others first, then build gradatum's own context layer (v0.7.0) on top of the same interface everyone else uses.

explore shipped features →

Connect Claude Code, IDEs, or any agent directly via MCP · Standard HTTP transport — no sidecar, no stdio pipe

v0.6.4 · studio hardening + security baseline

SILVER Studio Hardening + Security Baseline

✓ SHIPPED

Before a first public release, you owe it to users to be honest about what you are shipping. v0.6.4 is that honesty pass: a deep correctness audit surfaced twelve real bugs — including a regression that made some notes undeletable — and a security review tightened the admin UI to short-lived sessions, a strict content policy, and proper request size limits. The code index now covers five languages. This is the version that earns the right to be called stable.

Admin UI sessions expire in 1 hour — shorter window if credentials are ever compromised · Strict browser security policy (CSP) — no external scripts can run in the UI · Clickjacking protection added for older browsers · Request size capped at 512 KB — protection against oversized payloads · Code index now understands Rust, Bash, TypeScript, React (TSX), and Python · 12 correctness bugs fixed (note deletion, embedding index validation, internal API encapsulation) · 2337 tests pass

v0.6.5 · project-map management stabilization

SILVER Project-Map Management Stabilization

✓ SHIPPED

The project-map feature (structured feature lifecycle tracking with typed wikilinks as a canonical vault section) is now stabilized. v0.6.5 ships the complete feature cycle — release axis (roadmap / planned / released), deterministic duplicate detection, and a fail-closed CI gate. The public roadmap is reconciled to code ground-truth: CHANGELOG and git tags are now the authority, not separate documents. No new user-facing features — hardening and tooling before the context layer arrives in v0.7.0.

Feature lifecycle tracking — release axis (roadmap / planned / released) · Public roadmap reconciled to code ground-truth · Project-map validator + fail-closed CI gate · Deterministic card detection — no duplicate drift

v0.6.6 · anthropic-compatible local endpoint

SILVER Anthropic-Compatible Local Endpoint

planned

Claude Code and other Anthropic-API agents expect a /v1/messages endpoint. v0.6.6 ships exactly that — a local gateway that speaks the Anthropic Messages API and routes every call to a model running on your own hardware. The point is concrete: point Claude Code at gradatum and it runs end-to-end locally, with no request ever leaving your machine.

Serves the Anthropic /v1/messages API locally · Routes Claude Code (and any Anthropic-API agent) to a local model on your hardware · No request ever leaves your machine

Chapter II

Context & recall

v0.7.0 → v1.0.0 — Context assembly, proactive recall, identity, temporal search, and studio observability. v0.7.1–v0.7.5 are internal development milestones, published together as v0.7.6; v1.0.0 freezes the public API contracts and adds multi-user access with per-identity scopes.

v0.7.0 · memory layer + context assembly

Memory Layer + Context Assembly

✓ SHIPPED

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.7.1 · active recall

Active Recall

✓ SHIPPED

Memory is only useful if you can retrieve it. v0.7.1 adds proactive retrieval: gradatum autonomously surfaces relevant notes before you ask, recording which surfaced notes are actually used and bringing those decisions into context automatically.

Proactive note suggestions based on workflow · Surface forgotten decisions in real time

v0.7.2 · context efficiency

Context Efficiency

✓ SHIPPED

More context is not always better. v0.7.2 optimizes what gets included in each decision: only the most relevant notes are assembled, irrelevant context is pruned, and the quality of assembled memory improves measurably. This is where the vault stops being verbose and starts being precise.

Intelligent context pruning · Relevance-scored memory assembly · Reduced token usage without losing accuracy

v0.7.3 · identity — soul notes & acl

Identity — Soul Notes & ACL

✓ SHIPPED

Each agent has its own identity: a soul note that captures its invariants, operational gates, and personality. v0.7.3 ships this as a protected vault section. Every agent can store and retrieve its own identity; enumeration is hidden from unprivileged callers; reads and writes are guarded by per-agent JWT binding. This is the foundation for multi-agent reasoning.

Soul notes for agent identity · Per-agent identity sections protected by ACL · MCP server injects agent identity at initialize time · Identity enumeration hidden from unprivileged access

v0.7.4 · temporal search & decay

Temporal Search & Decay

✓ SHIPPED

Memory fades over time — and sometimes intentionally. v0.7.4 adds temporal search with from/to filters so agents can reason about what happened before or after a specific date. Recency decay down-weights stale notes in relevance scoring, keeping the vault focused on what still matters.

Temporal filters: search between two dates · Recency decay in relevance scoring · Chronological queries without external calendars

v0.7.5 · studio observability

Studio Observability

✓ SHIPPED

You cannot improve what you cannot see. v0.7.5 ships three observability features: real-time background task health, operational metrics charts, and a session activity trace browser — all in the admin studio. Operations are now transparent.

Real-time background job health · Operational metrics graphs in admin studio · Session activity trace browser

v0.7.6 · memory validation — deterministic quality gates

Memory Validation — Deterministic Quality Gates

✓ SHIPPED

Good memory requires good judgment. v0.7.6 ships a deterministic distillation quality gate: every note summary is scored on grounding (cosine similarity to source), importance factors, and penalty functions. Low-quality summaries are tagged and degraded, never silently dropped. Identity ACL is hardened with privilege checks on every read and write.

Deterministic distill quality scoring (0.0–1.0) · Grounding-based penalty for poor summaries · Quality tagging for low-score notes · Hardened identity ACL enforcement

v0.8.0 · vault stability — reversible deletion & hygiene

Vault Stability — Reversible Deletion & Hygiene

⚡ IN PROGRESS

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 · production baseline

GOLD Production Baseline

⚡ IN PROGRESS

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

v1.1.0 · storage backends & service discovery

Storage Backends & Service Discovery

planned

Gradatum runs on local SQLite by default, which keeps a deployment to a single file and a single machine. v1.1.0 makes that a configuration choice rather than a constraint: the vault can sit on replicated SQLite over libsql, or on object storage through S3, GCS, and Azure, without changing the storage interfaces the rest of the codebase depends on. Multi-process deployments also stop relying on hardcoded addresses — components register themselves and resolve each other at runtime.

Replicated SQLite backend over libsql — opt-in, same storage interface · Object storage backends: S3, GCS, Azure via OpenDAL · Components resolve each other at runtime — no hardcoded addresses

v1.2.0 · privacy — on-device pii redaction

Privacy — On-Device PII Redaction

planned

Notes ingested from mail, transcripts, or exported documents routinely carry personal data that nobody chose to store. v1.2.0 adds a redaction pass that runs before a note reaches the index: heuristic pattern matching first, then an on-device recognition model. Redacted fields are marked in the note itself, so downstream jobs can tell that a pass occurred instead of assuming it did.

Redaction pass applied before a note reaches the index · Heuristic pattern matching first, on-device recognition model second · Redacted fields marked in the note frontmatter

v2.0.0 · multimodal, consolidation & sovereign agent runtime

PLATINUM Multimodal, Consolidation & Sovereign Agent Runtime

planned

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

VIII · Quick start

Pre-built binaries, crates.io, or build from source.

View all install modes (7 profiles) Source on GitHub → See use cases (Without / With)
Clone & build (v1.0.0 · API stable)
# build from source
git clone https://github.com/gradatum/gradatum
cd gradatum && cargo build --release --workspace

# initialize a vault with the hierarchical preset
gradatum-admin init --preset hierarchical \
  --root /var/lib/gradatum

# start the server
systemctl --user start gradatum-server
Write & search (REST API)
# write a note (vault_write)
curl -X POST http://localhost:19090/api/v1/vault_write \
  -H "Authorization: Bearer $GRADATUM_BEARER" \
  -H "Content-Type: application/json" \
  -d '{"locus":"projecta/backend","section":"decisions","body":"Use ULID for stable note identity"}'

# search across loci
curl http://localhost:19090/api/v1/vault_search \
  -H "Authorization: Bearer $GRADATUM_BEARER" \
  -d '{"query":"ULID identity","locus":"projecta/*"}'

# list vaults
gradatum-admin vault list
MCP integration (MCP stub)
# gradatum.toml — MCP stub for Claude Code
[[mcpServers]]
name    = "gradatum"
command = "gradatum-mcp-stub"
args    = ["--server", "http://localhost:19090"]
env     = { GRADATUM_BEARER = "your-bearer-token" }

# Or via HTTP directly (API)
curl http://localhost:19090/health
curl http://localhost:19090/api/v1/vault_search \
  -d '{"query":"ULID","locus":"projecta/*"}'

v1.0.0 — current release. Pre-built binaries (server / llm / mcp) on GitHub Releases are still at v0.7.6 (latest published tag); source on GitHub (Apache-2.0), full workspace (27 crates) on crates.io — source releases. API stable since v1.0. See the Install page for all deployment profiles.