Ingest: Structure-Guided Document Chunking
Turns external documents (PDF, HTML, DOCX, Markdown) into indexed, searchable notes — preserving structural boundaries instead of splitting arbitrarily.
A skeleton tree parses the document hierarchy; each logical section becomes one atomic note, so a clause is never split across two chunks.
Table extraction converts tabular rows into indexable sentences (RowToSentence) so column relationships survive retrieval.
A noise filter discards non-informative nodes (table of contents, executive summaries, glossaries) that degrade retrieval quality.
Ingestion runs as a background Job::Ingest with progress tracking and automatic retry via the job queue.
For: Teams that need to import technical documentation, research papers, or meeting transcripts into the vault without losing the structural context that makes answers accurate.
Stable Wikilinks: Persistent Cross-Note Graph
Makes wikilink references between notes durable — links survive renames and deletions by anchoring to a stable ULID identifier rather than a file path.
A redirect_table maps every past title or path to the canonical ULID anchor, so [[old-title]] resolves correctly after the note is renamed.
Backlinks are indexed at write time, exposing links_in/links_out on every search result for graph-neighborhood traversal.
vault_search_multi merges results from multiple queries using Reciprocal Rank Fusion (RRF), so wikilink clusters surface naturally alongside keyword matches.
For: Knowledge engineers and developers who build interconnected notes and need cross-references to remain valid as the vault evolves over time.
Note History: Copy-on-Write Version Trail
Records a complete version history for every note write, so any previous state of a note can be retrieved or diffed without external tooling.
On each vault_write, the previous version is stored in a .history/<ulid>/ directory before the note is updated (Copy-on-Write semantics).
Dedicated history/* endpoints let callers inspect or restore any prior version by timestamp or sequence number.
Lifecycle configuration caps storage at max_versions=50 per note, pruning the oldest revisions automatically.
For: Developers and teams who need an audit trail of how knowledge evolved — including distillation drift detection and rollback of accidental overwrites.
Optimistic Locking: Safe Concurrent Writes
Prevents silent data loss when two processes write the same note concurrently, using a content-hash check instead of pessimistic locks.
vault_write accepts an optional write_if_match parameter containing the SHA-256 hash of the note version the caller last read.
If the stored note has changed since that read, the server returns 409 Conflict with a WriteConflict descriptor — the caller decides how to merge.
Writes without a hash succeed unconditionally, preserving backward compatibility for append-only workflows.
For: Developers building multi-agent pipelines or concurrent writer workflows where two agents may update the same note within the same time window.
Provenance Trust Score: Verifiable Note Lineage
Attaches a computed trust score to every note, derived from its origin and distillation history, so retrieved content carries verifiable lineage.
Trust is calculated from four sources: the writing agent, the distillation chain, the number of corroborating notes, and the confidence score at ingestion.
Distilled notes inherit a weighted mean of their source trust scores multiplied by the distillation confidence.
The trust field integrates with temporal decay (F-17): notes from less-trusted provenance decay faster in search ranking.
For: Teams running multi-agent pipelines who need to distinguish high-confidence knowledge from speculative or low-provenance notes before acting on retrieved content.
Temporal Decay: Recency-Weighted Search Ranking
Makes search results reflect how fresh and still-valid each note is — older or expired content scores lower without being deleted.
Each note carries a validity state (valid, temporal, or expired) and a document kind (static, versioned, or event), which together determine its decay profile.
A recency score computed relative to the current date is blended with the semantic score using a configurable temporal weight (default 0.40).
Event notes use a raw cosine relevance gate before decay is applied, preventing stale event records from surfacing on unrelated queries.
For: Agents and search clients that need results biased toward current knowledge — particularly useful for decision logs, meeting notes, and time-sensitive technical documentation.
Event-Log Vault: LLM Cost Attribution
Records every LLM call made by the vault with model, token count, estimated cost, latency, and the feature that triggered it — giving full budget visibility per feature.
A QaEvent struct is captured by the gateway intercept layer at each LLM completion: model identifier, prompt/completion token counts, cost estimate, latency, and a feature_id tag.
Events are stored in an append-only event_log table, queryable via the jobs introspection API for per-feature cost breakdowns.
The event log feeds the distillation learn job (F-22), which uses token patterns to identify cost-optimization candidates over time.
For: Operators who need to understand which vault features drive LLM spend, and developers building cost-attribution dashboards or budget-alert workflows on top of the vault.
Privacy Filter: Automatic PII Redaction on Write
Intercepts every note before it is stored and redacts personally identifiable information (PII) — without an external API call or network dependency.
The PrivacyFilter is registered as a WriteHook on DocumentStore; it runs synchronously on every vault_write before the note reaches the index.
The initial textual pass uses heuristic pattern matching. A later ONNX (portable neural network runtime) Named Entity Recognition model runs fully on-device with no data leaving the host.
Filtered fields are marked in the note frontmatter so downstream processes know redaction has occurred.
For: Developers ingesting documents that may contain personal data — emails, transcripts, HR notes — and operators who need a compliance-friendly vault with no third-party data processing.
Drift Detection: Identity Write Hook
Detects unauthorized or unexpected changes to an agent's identity notes and flags them before they silently alter agent behavior.
A DriftDetector is registered as a WriteHook on DocumentStore at startup; it monitors writes to the identity/ locus without a direct vault dependency.
On each write, the detector computes a semantic distance between the new content and the last validated version; divergence above threshold triggers a drift_detected event.
The drift event is surfaced via the jobs SSE (Server-Sent Events) stream, allowing operators or higher-level workflows to review the change before it takes effect.
For: Operators running persistent agents whose identity notes must not change without explicit authorization — detecting accidental overwrites and adversarial prompt-injection attempts.
VaultScope: Multi-Vault and Multi-Agent Addressing
Introduces a single addressing type that targets any locus across multiple vaults and agents with a single, unambiguous address — usable from any background job without per-job workarounds.
VaultScope encodes the vault identifier, the agent identifier, and the locus path as a single composable value, eliminating ambiguity when multiple vaults share a worker.
Every background job (distillation, purge, audit, migration, and others) carries a VaultScope, making cross-vault operations a first-class primitive rather than a per-job workaround.
All existing jobs are migrated to use VaultScope in a single coordinated change — no incremental per-job migration is needed.
For: Developers building multi-agent systems where several agents share or exchange knowledge across isolated vaults, and need deterministic addressing for background jobs.
Vault Lifecycle Management: State Machine, Retention and History Pruning
Adds an explicit note lifecycle state machine (Draft → PendingReview → Live → Deprecated → Garbage) and declarative retention rules — keeping the vault compact and high-quality automatically.
Each note carries a lifecycle_state field; transitions are explicit API calls with optional guard conditions so no note skips a required validation step. Draft notes are excluded from search by default; Deprecated notes are downweighted.
Operators define [[vault.lifecycle]] rules in TOML: conditions such as age, decay score, or locus pattern trigger a Job::Purge(Lifecycle). The purge job runs after distillation so no note is deleted before its value has been extracted.
Configurable history pruning caps per-note version history with max_versions and a TTL, preventing unbounded growth of the .history/ directories.
For: Operators who want the vault to self-regulate quality over time, and teams building multi-agent pipelines that need a formal quality gate between note production and retrieval.
Semantic Forget: Intentional Scoped Deletion
Lets operators explicitly remove a topic or locus from the vault — with a mandatory dry-run preview, double confirmation, and progressive decay instead of immediate deletion.
vault_forget(scope, dry_run: true) returns the full list of affected notes and any derived skills before any state change — the operator reviews and confirms explicitly.
On confirmed deletion, notes are marked forgotten=true and decay accelerates over a configurable window, removing them from search results progressively rather than immediately.
Cascade behavior is configurable: forgetting a knowledge/ topic can optionally propagate to linked skills/ and peers/ entries derived from it, with each cascade step listed in the dry-run preview.
For: Teams or individuals removing a project, topic, or person from the vault intentionally — with full visibility into what will be affected before committing, and a decay window to undo.
Temporal Index Foundation: Chronological Memory Queries
Lays the foundation for time-aware vault queries — a chronological index from note frontmatter lets agents ask what happened before, after, or around a date without a calendar or graph database.
A TemporalIndex is derived at write time from frontmatter fields (occurred_at, valid_from, event-date, created) — no LLM extraction, no separate store. This release ships the index and the vault_timeline API surface; higher-level temporal reasoning ships in v0.5.0.
The vault_timeline tool exposes before/after/around/upcoming queries; the index is fully reconstructible via a ReIndex job if frontmatter changes.
Job::Validate cross-checks temporal contradictions between notes (e.g., two notes asserting conflicting event orders) as part of the memory validation pipeline.
For: Agents and developers who need to reconstruct decision timelines, detect sequencing contradictions, or surface upcoming-deadline notes — without adding a calendar or graph infrastructure.
Distill: Scheduled Knowledge Compression
Automatically compresses accumulated raw notes into compact, reusable knowledge — running as scheduled background jobs while the vault is idle.
Four distillation modes run as Job::Distill: Semantic (synthesizes topic clusters into a single knowledge note), Learn (requires enough recorded LLM interactions (QaEvents) to extract meaningful cost and quality patterns), Peer (requires ≥5 sessions, builds a user behavior profile), and Rationale (preserves the reasoning chain behind decisions).
Distilled notes inherit a trust score computed from their source notes, and a Note History fingerprint is stored so drift from the validated version can be detected later.
DistillSource supports multi-vault targeting via VaultScope, allowing a distillation job to draw from notes across isolated vaults.
For: Developers running long-lived agent sessions who want raw notes compressed into searchable knowledge automatically — and teams building shared knowledge stores that grow in quality over time.
Lessons Recall: Dedicated Endpoint, MCP Tool, and Hook
Surfaces distilled lessons-learned notes on demand via a dedicated recall endpoint, a native MCP tool, and an agent hook — making accumulated lessons actionable at decision time.
A dedicated GET /api/v1/lessons/recall endpoint queries the lessons-learned corpus with semantic search and returns ranked results with source attribution.
A vault_lessons_recall MCP tool exposes the same surface directly to MCP clients, with optional role and tag filters so agents retrieve only domain-relevant lessons.
A pre-action hook fires automatically when the agent is about to start a new task, injecting the top-3 matching lessons into the context before the first response.
For: Developers and agents who want past mistakes and validated patterns surfaced automatically before acting — not just stored somewhere and manually searched.
Multimodal Gateway: OpenAI Content-Array and Vision Routing
Extends the gateway to accept the OpenAI content-array message format and route vision requests to an appropriate model — enabling multimodal inputs without changing the vault API.
The gateway parses ChatMessage::User as either a plain string or a Vec<ContentPart> (text + image_url), matching the OpenAI chat completions schema, so existing text-only clients are unaffected.
A vision routing gate inspects the content array at request time: messages containing image parts are forwarded to a configured vision-capable endpoint; text-only messages follow the standard routing path.
Configuration exposes a vision_endpoint field in the gateway TOML; if unset, image-bearing requests return a 422 with an explicit error rather than silently stripping the image.
For: Developers building agents that process screenshots, diagrams, or documents alongside text, and operators who want multimodal inputs handled at the gateway layer without routing logic in each client.
Code-Map: Multi-Language Source Indexing with Reverse-Dependency Graph
Extends code search to multiple languages with a reverse-dependency graph — find every call site instantly without regex scanning.
Language-specific parsers extract definitions and call sites from source files; a unified code graph stores both forward dependencies (what a function calls) and reverse dependencies (what calls this function).
The reverse-dependency index powers questions like "every place this function is used" — no regex scanning required, instant query results on any codebase.
Symbol resolution is deterministic and language-aware: method names, free functions, imports, and exports are properly disambiguated without semantic analysis.
For: Teams maintaining polyglot codebases needing call chain understanding across multiple languages.
VaultScope Patterns: Wildcard and Role-Filtered Agent Fan-Out
Extends F-31's addressing from one target to many: a single scope pattern with wildcards and role filters reaches a set of agents in parallel, and merged results still respect agent boundaries.
Query scoping extends beyond single-agent addressing to reach multiple agents in parallel: scope definitions support wildcards and role filters so a distillation job can consolidate knowledge across all agents matching a pattern.
Audit and compaction jobs can target a vault region or agent role rather than hard-coded addresses, making deployments flexible without custom per-agent coordination.
Result merging respects agent boundaries so data stays isolated; a unified result set optionally labels which agent each note came from.
For: Operators managing multi-agent deployments with distributed knowledge consolidation and querying.
F-64 planned Backlog · no target version
#
Compliance Forget: Retention Classes with Tamper-Evident Audit Trail
Adds a compliance layer over F-44: a tamper-evident audit trail of every forget, declarative retention classes, and a graduated decay window after which the note can no longer be recovered.
Compliance mode appends a record of each forget to an append-only audit log, cryptographically hashed against the previous entry, so the trail of what was forgotten, and when, is tamper-evident.
Retention policies are declarative: notes tagged with a retention_class are automatically forgotten when their retention window expires, without manual review.
Graduated decay supports GDPR right-to-be-forgotten: rather than erasing on request, a configurable window keeps the note recoverable; once that window expires the note can no longer be recovered, and the forget stays in the audit log.
For: Teams handling regulated data requiring audit-trail deletion compliance.
Temporal Index Foundation: Chronological Memory Queries — suite F-55
Extends temporal queries with causal chains, concurrent clusters, and historical trends for timeline reconstruction and anomaly detection.
A TemporalGraph models temporal relationships between events — not just individual timestamps but causal chains (A caused B) and concurrent clusters (A, B, C happened at the same time).
Historical trend queries reconstruct how a quantity changed over time: "what was the decision at date X" becomes "show me the decision, how it evolved, and what triggered each change".
Anomaly detection over the temporal index flags notes with temporal contradictions (event A claims to happen after B, but the timestamps say B happened later) — surfaced to the validation pipeline automatically.
For: Researchers and analysts needing to reconstruct event timelines and detect temporal contradictions.
libsql Remote: Replicated SQLite Backend
Adds an opt-in remote SQLite backend powered by libsql, enabling vault replication and read replicas without changing the DocumentStore interface.
The gradatum-db-sqlite crate exposes a libsql feature flag; enabling it replaces the local SQLite connection with a remote libsql endpoint.
The DocumentStore, IndexStore, and QueueStore traits remain unchanged — the swap is purely a configuration-level choice with no application code changes.
An internal poll loop on the libsql queue backend (500 ms interval) bridges the remote queue to the existing channel-based worker dispatch.
For: Operators who need vault data replicated across machines or want read replicas for high-read workloads, without migrating to a heavier database engine.
LanceDB Vector Backend: Scalable Embedding Store
Replaces the default SQLite vector store with LanceDB for workloads where Approximate Nearest Neighbor (ANN) search on large embedding sets becomes a bottleneck.
The gradatum-db-lancedb crate implements the VectorStore trait backed by LanceDB, an embedded columnar vector database.
Switching is opt-in via configuration — IndexStore (full-text) stays on SQLite; only the vector path moves to LanceDB, keeping the deployment simple.
A Parquet-backed DocStore variant (planned for a later phase) will extend LanceDB to cover document storage as well for very large vaults.
For: Developers with vaults exceeding tens of thousands of notes who find SQLite ANN performance insufficient, and contributors who want to benchmark retrieval quality across storage backends.
gradatum-studio: Vault Management Interface
A local web interface for reading, searching, reviewing, and monitoring the vault — without exposing any API key or modifying the vault write path.
Five surfaces ship in the MVP: a dashboard (live vault metrics and recent activity), a note browser with inline markdown rendering, a search panel with score and section filters, a review queue (notes pending lifecycle validation), and a jobs monitor showing background task status.
Authentication is handled via a single API key injected at startup; no OAuth or user database is required for the single-user deployment.
A WHY scores panel surfaces the curator confidence and section classification for each note — making the reasoning behind search ranking visible and auditable.
The interface is read-only for vault content by design; writes still go through the standard API so the vault write path remains the sole source of truth.
For: Developers and operators who want to inspect and monitor their vault through a browser rather than raw API calls, without adding infrastructure or weakening data sovereignty.
gradatum-mcp: Native Model Context Protocol Server
Exposes the full vault API as a native MCP (Model Context Protocol) server — usable from any MCP-compatible client without an intermediary stub.
The gradatum-mcp crate publishes vault tools (vault_write, vault_search, vault_forget, vault_timeline, and others) as MCP capabilities with full JSON Schema definitions.
Authentication is handled MCP-side, decoupled from the HTTP API auth layer, so the MCP surface has its own access control.
The stdio transport (for local clients) and the Streamable HTTP transport (F-56, for remote clients) are both supported from the same crate.
For: Developers using MCP-compatible LLM clients (Claude Desktop, Cursor, custom agents) who want direct vault access without installing a local proxy stub.
Streamable HTTP Transport: Load-Balancer-Friendly MCP
Implements the MCP 2025-11-25 Streamable HTTP transport — a single /mcp endpoint that works with load balancers, serverless runtimes, and mobile clients.
A single POST+GET /mcp endpoint handles all MCP traffic; responses are either plain JSON or upgrade to Server-Sent Events (SSE) per-request, without maintaining a persistent connection.
This replaces the deprecated HTTP+SSE transport (spec 2024-11-05), which required a persistent SSE connection incompatible with most load balancers.
The local stdio transport is preserved for desktop clients; optional backward-compatible SSE mode allows a smooth migration for existing integrations.
For: Operators deploying gradatum behind a reverse proxy or in a containerized environment, and mobile MCP clients (Claude for iOS/Android) that require a stateless HTTP transport.
Memory Validation: Self-Healing Before Storage
Intercepts distilled notes before they enter long-term memory, corrects detectable errors automatically, and discards notes that cannot be repaired.
A background validation job computes a composite quality score; notes above a configurable threshold are accepted, notes with specific error patterns are routed to a repair strategy.
Three repair strategies: contradiction patch (corrects numeric contradictions against source notes), entity scrub (removes hallucinated entity claims), and grounding rewrite (reconstructs under-anchored text from source material). Internally: ContradictionPatch, EntityScrub, GroundingRewrite.
Repaired notes are stored with an audit flag (HEALED_ACCEPT) and a change log; notes that cannot be repaired are discarded cleanly — never silently stored.
For: Teams where distillation quality is critical — RAG pipelines, shared knowledge bases, long-running agents — who cannot afford hallucinated or contradictory notes accumulating in the vault.
Multi-User Support: Per-User Vault Isolation
Enables multiple users to share a single gradatum deployment with configurable isolation — private identity, shared or private knowledge, role-based access.
Each user is represented by a UserRecord with a Bearer JWT; an admin invitation flow provisions new users without exposing the root credential.
Isolation is per-locus type: identity/ and peers/ are always private; knowledge/ and skills/ are configurable as shared or private per deployment.
ACL policies in gradatum-acl-policy enforce locus-level access at the storage layer, so isolation is structural rather than enforced only at the API boundary.
For: Teams and households who want to run one gradatum instance shared across multiple people or agents, each with their own private memory and optionally contributing to shared knowledge.
F-57 planned Backlog · no target version
#
OAuth MCP: Remote Access for Mobile and ChatGPT
Enables gradatum to be reached from mobile MCP clients and ChatGPT without weakening sovereignty — using a self-hosted OAuth 2.1 authorization server.
Gradatum acts as an OAuth 2.1 resource server: it validates tokens and publishes Protected Resource Metadata (RFC 9728) but delegates token issuance to a self-hosted identity provider using OIDC (OpenID Connect) — such as Kanidm.
The IdentityProvider trait decouples the identity provider from gradatum-auth (D-14), so the IdP is replaceable without modifying the authorization layer.
PKCE (Proof Key for Code Exchange) S256, Dynamic Client Registration, and explicit consent flows are required — bearer-static tokens are not accepted, matching what Claude for mobile and ChatGPT require.
For: Operators who want to reach their vault from a mobile MCP client or ChatGPT without a VPN, and who want token rotation, explicit consent, and centralized revocation instead of static bearer tokens.
Vault Audit and Deduplication: Scheduled Quality Pass
Runs a scheduled audit pass over the vault to detect duplicate notes, score the vault's overall knowledge quality, and produce a conflict report.
Job::Audit(AuditMode) supports three modes: Detect (identifies duplicates and near-duplicates by semantic similarity), Deduplicate (merges or flags them), and Both (full pass).
The audit produces a per-locus vault score reflecting coverage, freshness, and uniqueness — visible in the jobs introspection API.
Conflict reports list notes with contradictory claims so operators or distillation jobs can resolve them explicitly rather than leaving ambiguity in the search index.
For: Operators maintaining long-lived vaults where notes accumulate from multiple agents or ingestion pipelines, and who need a systematic quality baseline rather than ad-hoc manual review.
Gateway: Local LLM Proxy for Chat, Embeddings, and Reranking
Provides a single local HTTP gateway in front of the LLM and embedding backends, so gradatum components talk to one stable endpoint instead of many provider-specific ones.
The gradatum-gateway crate exposes OpenAI-compatible routes — chat completions, embeddings, reranking, and model listing — over a local HTTP port.
Requests are routed to the configured local backends, decoupling gradatum from any specific inference server and keeping all traffic on the host.
For: Operators running gradatum fully locally who want a single, stable inference endpoint that other components and tools can target without per-backend wiring.
Dead Letter Queue and Job Resilience
Captures jobs that exhaust their retries into a Dead Letter Queue instead of losing them, so failed background work is auditable and replayable.
Each job carries a retry budget; once exhausted, it is moved to a Dead Letter Queue (DLQ) rather than silently dropped.
Multiple workers coordinate through the shared queue with at-most-once execution per job, and a graceful 30-second drain on shutdown lets in-flight jobs finish before the process exits.
DLQ entries retain their failure context so operators can inspect the cause and requeue once the underlying issue is fixed.
For: Operators running gradatum with background ingestion or distillation jobs who need guarantees that transient failures never result in silently lost work.
Jobs Introspection API: Observable Background Work
Exposes the async job queue over HTTP so callers can submit, track, and stream the progress of background work in real time.
Five HTTP endpoints cover the job lifecycle — submit, list, fetch a single job, stream progress, and inspect queue state.
Server-Sent Events (SSE) push live progress updates to clients without polling, and an Idempotency-Key header makes job submission safe to retry.
Queue depth and per-status counters are exported in Prometheus format for dashboards and alerting.
For: Integrators who drive ingestion or maintenance jobs programmatically and need to observe their progress and outcome rather than firing blind.
Cross-Encoder Reranking for Precise Retrieval
Re-scores candidate search results with a cross-encoder model so the most relevant notes rise to the top, beyond first-pass keyword and vector ranking.
After the initial retrieval, the gradatum-gateway /v1/rerank endpoint scores each query-document pair with a BGE-reranker-v2-m3 cross-encoder running locally on ONNX Runtime.
The reranked order replaces the fused first-pass ranking, improving precision on the top results returned to the caller.
For: Developers whose retrieval quality depends on surfacing the single best note for a query, where first-pass ranking alone is not precise enough.
Secrets Dependency Injection: Provider-Backed Credentials
Decouples gradatum from any single secret source through a SecretsProvider trait, so credentials can come from the environment, a file, or a future vault backend without code changes.
A SecretsProvider trait abstracts secret resolution, with EnvSecretsProvider and FileSecretsProvider implementations shipped by default.
Resolved secrets are wrapped in a SecretBytes type that zeroizes on drop and masks its Debug output, so credentials never leak into logs or memory dumps.
For: Operators with strict credential-handling requirements who need secret sourcing to be configurable and auditable rather than hardcoded.
Curator Confidence Ladder: Graded Note Admission
Routes incoming notes through a confidence ladder so high-confidence content is admitted directly while uncertain content is held for review instead of polluting the index.
The curator classifies each note and assigns a confidence band; low-confidence notes are routed to a PendingReview state rather than going live immediately.
A dedicated curation kind (c_kind) column, added in migration 0008, records the classification decision so admission outcomes are queryable and auditable.
For: Vault maintainers ingesting content from heterogeneous or noisy sources who want automatic triage to protect overall index quality.
Reference-Language Memory: Pass-by-Reference Context
Lets agents pass note references instead of full note bodies into the LLM context, keeping prompts compact while preserving the ability to resolve content on demand.
Context assembly passes stable note references rather than inlined bodies, and the referenced content is resolved only when the model actually needs it.
This reduces token pressure on long agent sessions while keeping every reference traceable back to its canonical note.
For: Integrators building long-running agents that hit context-window limits and need to keep prompts lean without losing access to source notes.
Curator Threshold Tuning — continuation of F-42
Completes the curator confidence ladder by finalizing the admission and review thresholds left open after the initial F-42 delivery.
Builds on the released curator ladder (F-42) to settle the remaining confidence cut-offs that govern direct admission versus held-for-review routing.
The candidate threshold values are still under architectural review, so this continuation tracks the tuning work separately from the shipped baseline.
For: Vault maintainers who need the curator admission policy tuned to their own quality and noise profile rather than relying on the initial defaults.
F-67 planned Backlog · no target version
#
Event-Log Cost Breakdown Query API — suite F-19
Completes event-log cost attribution by adding a query API that surfaces cost breakdowns per feature, per model, and per time window.
Builds on the released F-19 event log infrastructure (QaEvent struct, append-only storage, 90-day retention) to expose a dedicated cost-breakdown endpoint.
Queries span multiple dimensions: cost_per_feature (rolls up all LLM calls tagged with a feature_id), cost_per_model (aggregates by model identifier), and cost_per_day (trends over time).
Results include estimated cost, token usage, and call frequency, enabling operators to identify cost-optimization opportunities and track spend trends over weeks.
For: Operators and cost analysts who need granular visibility into where vault LLM spend is going, and developers building cost-attribution dashboards.
Lessons Recall Pre-Action Hook — suite F-60
Completes lessons recall by adding an automatic pre-action hook that fires before the agent starts a new task, injecting relevant prior lessons into the context.
Builds on the released F-60 endpoint and MCP tool to add the remaining pre-action hook surface.
When the agent is about to start a new task, the hook automatically queries the lessons-learned corpus with semantic search, retrieves the top-3 matching lessons, and injects them into Zone A of the context before the first response.
Configuration allows operators to tune the hook sensitivity, lesson count, and filters (by domain, role, or tag) so lessons are contextually relevant and not overwhelming.
For: Developers building agents where automatic access to prior lessons before acting is critical — reducing repeated mistakes and accelerating decision quality.
F-69 planned Backlog · no target version
#
Distill Learn/Peer/Rationale Modes — suite F-22
Completes the distillation pipeline by shipping the Learn, Peer, and Rationale modes deferred from the F-22 Semantic-only release.
Builds on the released F-22 Semantic distillation mode to add three additional modes: Learn (extracts cost and quality patterns from QaEvents), Peer (builds user behavior profiles from session interactions), and Rationale (preserves the reasoning chain behind distilled decisions).
Each mode runs as a background Job::Distill variant with its own criteria, frequency, and output format.
All modes integrate with F-17 (trust scoring) and F-55 (temporal index) so distilled notes inherit verifiable lineage and can be queried by time.
For: Operators running multi-session vaults where automatic extraction of learning patterns and behavior profiles becomes valuable as the vault matures.
Code-Map Qualified Method-Call Resolution — suite F-62
Completes the code index by adding qualified method-call resolution, so "Type::method()" is correctly resolved to the specific implementation without ambiguity.
Builds on the released F-62 code-map reverse-dependency graph to handle the partial case: self.method() calls and qualified calls like Type::method() that require type inference.
Language-specific type resolution is added per language (Rust trait resolution, TypeScript class hierarchies, Python method resolution order).
Results include the resolved target implementation, qualified with its module and defining type, so call chains are fully traceable.
For: Code maintainers and refactoring tools where knowing the exact implementation that a method call targets is critical to safety and correctness.
Queue DAG: Job Dependency Chains
Lets background jobs depend on each other — a job can declare that it waits for one or more prior jobs, and the queue ensures the dependency chain is respected.
Each job carries an optional await_jobs list of ULID references to prior jobs that must complete before this one can run.
QueueStore::find_awaiting(job_id) queries for predecessors using LIKE-based locus prefix matching to avoid collision; QueueStore::set_pending(job_id) idempotently promotes a job from Waiting to Pending once all its dependencies are satisfied.
When a job completes, the queue runs a cascade promotion sweep to identify newly unblocked dependents; if promotion fails, a recovery sweep runs on the next worker cycle.
For: Operators running complex background pipelines where one job must wait for another to finish — ingestion triggering distillation, or distillation triggering validation.
Agent Action Tracing
Records every agent action — what ran, when, what it touched, and why — in an append-only log queryable for 90 days without external storage.
POST /api/v1/session-log/trace accepts agent action events (fire-and-forget, no update or delete) with fields: agent_id (stable server identifier from JWT sub), session_id, tenant_id, ts_ms (millisecond timestamp), action_type (enum), target (resource affected), intent (what the agent was trying to do), outcome (success/failure), marker (link to decision), and ref (pointer to related note).
Storage is append-only; retention is configurable via [session_trace] retention_days (default 90).
Queries via vault_timeline can reconstruct what an agent did in a session without storing personally identifiable data.
For: Operators who need an audit trail of agent activity without relying on external logging infrastructure, and teams building compliance or security workflows.
Proof-of-Absence Search Signal
Adds a signal to search results that distinguishes "the topic is truly absent from the vault" from "the topic is present but not ranked high enough".
vault_search now accepts an optional include_corpus_count parameter (opt-in, zero overhead by default).
When enabled, results include corpus_count: the total number of notes in the vault that matched the query at any score level (even below the ranking threshold).
A corpus_count of 0 proves the topic is absent; a corpus_count > len(results) proves the topic exists but was filtered or re-ranked below the top-K.
For: Developers building workflows where it is critical to know whether information is truly missing versus just not highly ranked.
Native TLS Termination
Adds native TLS 1.2+/1.3 support to the gradatum server, eliminating the need for a reverse proxy just to enable encryption.
The gradatum-server binary accepts [tls] configuration: cert_path (PKCS#8 certificate), key_path (private key), and optional min_tls_version (default 1.2).
TLS termination happens at the socket layer; the HTTP API and MCP surface both run over the same encrypted connection.
No external proxy, no sidecar — encryption is built in.
For: Operators deploying gradatum on private networks who need encryption without adding a reverse proxy or external gateway.
F-80 planned Backlog · no target version
#
gradatum-as-channel: Proactive MCP Push
Lets gradatum initiate — push a relevant memory to your agent before you ask, instead of only answering when queried.
Exposes gradatum as an MCP channel capable of server-initiated notifications, not just request/response.
When a trigger fires (a new note, a scheduled recall), gradatum pushes the relevant context to the connected agent.
The agent receives proactively surfaced memory without polling the vault.
For: Agent builders who want a memory layer that volunteers relevant context proactively, rather than only on explicit retrieval.
F-81 planned Backlog · no target version
#
HippoRAG-2 Associative Recall: PPR over Wikilink Graph
Associative recall that follows the wikilink graph — surfacing notes connected to your query, not just lexically or semantically similar ones.
Seeds Personalized PageRank (PPR) from the notes that match a query, then propagates over the note wikilink graph.
Implements the HippoRAG-2 associative-memory approach: graph propagation surfaces indirectly-linked but relevant notes.
Complements lexical and semantic search with structural, relationship-aware recall.
For: Users with densely interlinked vaults who want recall to follow connections that a keyword or embedding match alone would miss.
Arbor HTR: Research Spike
An exploratory research track evaluating Arbor for handwritten-text recognition (HTR) as a possible future ingest path — framed as a spike, not a commitment.
A time-boxed research spike, not a planned deliverable: evaluates the Arbor approach to handwritten / document-image text recognition.
Probes the feasibility of turning handwritten or structured documents into vault-ingestible notes.
The outcome decides whether this graduates into a committed feature or is shelved.
For: Forward-looking users curious about gradatum ingesting handwritten or document-image sources; explicitly exploratory.
Router Dispatch: SmartRouter Capacity
Routes incoming requests to the appropriate local backend based on task type and available inference capacity.
SmartRouter evaluates the request type and current backend load, then forwards the request to the best-available local model or API endpoint.
Routing decisions are transparent to callers: the same endpoint handles all request types, and selection logic is configurable without application changes.
For: Backend operators running multiple local backends who need transparent routing without client-side dispatch logic.
Engine HTTP Supervisor: llama-server Lifecycle Manager
Manages the llama-server process lifecycle, exposing stable model inference over a local HTTP endpoint.
A supervisor process starts, monitors, and restarts llama-server on failure, presenting a stable HTTP endpoint regardless of engine restarts.
Health probes detect stalls and trigger a clean restart without dropping the listening socket from the caller's perspective.
For: Local deployments where stable inference availability across process restarts and crashes is required.
Job Enum and JobRecord: Five-Block Apalis Worker
Defines the structured job taxonomy and typed execution blocks for the Apalis background worker.
Five typed job blocks (Ingest, Distill, Validate, Embed, Expire) map to Apalis job workers, each with its own error handling and retry policy.
JobRecord persists job identity, status, and failure context so the queue is introspectable without external logging.
For: Backend operators who need to inspect, extend, or audit the background job processing pipeline.
F-83 planned Backlog · no target version
#
Doc-Map: Reference Documentation Index
Maintains a queryable index of reference documentation to reduce token cost and prevent stale content from degrading recall.
A scheduled job walks configured documentation sources, extracts structural headings, and persists a lightweight doc-map note per source.
Queries against the map surface the canonical section rather than re-ingesting entire documents, keeping token overhead low.
For: Teams importing large reference materials who want fast targeted retrieval without redundant full-text overhead.
F-84 planned Backlog · no target version
#
OKF Interop: Open Knowledge Format Export
Exports the vault as an Open Knowledge Format bundle for interop with external knowledge management tools.
An export command serialises vault notes, wikilinks, and metadata into a standards-compliant OKF bundle.
The bundle can be imported into compatible tools or archived as a portable, documented knowledge backup.
For: Users who want to migrate their vault, share it with collaborators on other tools, or archive it in a portable format.
On-Demand Delete: Reversible Archival with Retention GC
Removes a note from the live vault by moving it to an archive tree instead of erasing it — recoverable until a configurable retention deadline, after which it is physically destroyed.
A delete moves the note's Markdown file and its .history/ directory under .archive/ in mirror layout and records a row in the registry-driven archive_index table; a durable JSONL audit tombstone is written before the cascade.
A boot-and-interval GC selects archives past their 60-day (configurable) retention deadline from the registry — never a filesystem scan — and destroys them physically; destroyed and restored rows survive as history traces.
Restoring re-indexes the note as pending-review so it re-enters the curator pipeline rather than returning straight to live, with a 409 on ULID collision.
The gradatum-admin CLI drives delete, archive listing, purge, and restore (single ULID or a from/to range) dry-run by default over a loopback admin namespace; MCP exposes vault_archives_list read-only, so agents can see archives but never mutate them.
For: Operators who need to take notes out of the live vault without an irreversible step, and who want a review window plus an audit trail before anything is physically destroyed.
F-101 planned Backlog · no target version
#
Memory Self-Healing: LLM Drift Validation (F-43 child)
Extends the deterministic quality gate with an LLM-powered healing phase that rewrites low-quality summaries.
Notes tagged quality-low by the deterministic gate (F-43) are queued for a healing job that rewrites the summary against the source body using an LLM.
The healed note is re-scored; if the new score clears the threshold it is promoted to live status. Healing runs asynchronously and is fully auditable.
For: Vaults where automated ingestion produces many low-quality summaries and manual curation is not practical at scale.