HomeProductscaveauMEMHow it works
caveauMEM · How it works

Memory that thinks in tiers.

Under the hood, caveauMEM is a tiered memory engine with hybrid, graph-aware recall and a governed learning loop. This page walks the mechanism end to end — then shows Boris, a live autonomous agent wired into it on every turn.

Create an account Back to caveauMEM
The mental model

Three ideas do all the work.

Everything below is an elaboration of these three: how memory is found, how it is layered, and how it stays trustworthy.

Recall

Find the right memory

Hybrid dense + keyword search, expanded along a memory graph, so the right note surfaces even when the wording has drifted since you saved it.

Tiers

The right horizon

Durable knowledge, short-term scratch, and a replayable episodic timeline are kept apart — each recalled when it actually matters.

Governance

Memory you can trust

Per-client and per-user scoping, an encrypted secret vault, and a human-in-the-loop review before anything becomes shared truth.

Diagram 1 · The engine

One endpoint, four tiers, three stores.

A single MCP endpoint fronts four memory tiers. The persistent tier is backed by a vector store, a lexical index, and a graph — fused at recall time and packed into a token-budgeted context.

caveauMEM engine: an MCP memory endpoint feeds persistent, scratch, episodic and secret-vault tiers. The persistent tier writes to Qdrant vectors, MariaDB BM25 and a FalkorDB graph, which memory_recall fuses and the memory_context assembler packs alongside scratch and episodic memory. MCP endpoint /api/mcp/memory/* Persistent notes documents + chunks Ephemeral scratch TTL 1–7d Episodic log TTL 30–90d Secret vault AES-256-GCM Qdrant vectors MariaDB BM25 FalkorDB graph memory_recall hybrid + graph RRF memory_context token-budgeted assembler
The vault stands apart by design — secrets are fetched by exact key, never embedded or recalled. Scratch and episodic memory skip the stores entirely and feed the assembler directly.
Diagram 2 · How recall fuses

Two retrievers, a graph, one ranking.

Dense vectors catch meaning; BM25 catches exact terms. Reciprocal Rank Fusion blends them, the top hits seed a graph walk, and a second weighted pass produces one ranked, budgeted context.

Recall pipeline: a query runs through a dense vector retriever and a BM25 lexical retriever, fused by RRF; the top hits seed graph neighbours; a weighted second RRF re-rank produces a token-budgeted context. seeds query Dense vector embeddings BM25 lexical FULLTEXT RRF fusion k = 60 Weighted re-rank 2nd RRF · w_graph Graph neighbours co-tag + supersedes Budgeted context
Single-mode search misses: pure vectors fumble exact identifiers, pure keyword misses paraphrase. Fusion plus a graph hop is what makes recall hold up as wording drifts.
The governed learning loop

The agent proposes. A human promotes.

Memory that edits itself unsupervised is a liability. caveauMEM captures what agents learn, distills it into candidates, and gates every change behind a human.

Step 01

Capture

Agents flag a note helpful, wrong, outdated, or missing as they work. Raw signals land in a queue — nothing in the corpus changes yet.

  • memory_feedback signal
  • helpful / wrong / outdated / missing
  • tenant + user scoped
  • no embedding at capture
Step 02

Distill

A low-cost model clusters the signals and drafts improved notes as candidates. They are proposals only — never auto-embedded into recall.

  • Clusters by note
  • Cheap internal model draft
  • Candidates stay plaintext
  • Provenance recorded
Step 03

Curate

A curator approves or rejects each candidate in the portal. Only on approval is a note embedded and made recallable. The agent proposes; a human promotes.

  • Human approve / reject
  • Approve → embed
  • Reject → audited
  • Closes the loop
Case study · Boris

A live agent that runs on caveauMEM.

Boris is an autonomous strategy agent built on the Hermes runtime, with a cost-efficient Claude Haiku brain. He is not a chatbot with a system prompt — he reads and writes caveauMEM on every turn. Here is the exact wiring.

Hook

Pre-LLM memory hook

Before Boris’s brain ever sees a message, a deterministic hook calls memory_bootstrap and recalls his recent episodic timeline, then injects them as context — every session, automatically. (Prompt-only directives proved unreliable; the hook guarantees it.)

Skills

Skills from the registry

Boris’s playbooks are served from the caveauAI skill registry, not baked into the box. Edit a row server-side and the new behaviour ships on his next session — no redeploy, no SSH.

Episodic

Episodic self-logging

Meaningful exchanges are written back to the episodic tier, so Boris stays coherent across long-running work instead of starting every session cold.

Review

Nightly learning-review

A scheduled review curates his own memory each night and reports the result to Telegram — the governed learning loop, running on autopilot.

Diagram 3 · Boris × caveauMEM

One turn, start to finish.

Every message Boris receives passes through the same memory-aware path before his brain answers — and a nightly review keeps that memory curated on its own.

A Boris turn: a message reaches the Hermes gateway, the pre-LLM hook bootstraps and recalls memory plus skills from caveauMEM, the Haiku brain answers, the exchange is logged episodically, and a nightly learning-review cron curates memory and reports to Telegram. Dave Gateway Hermes Pre-LLM hook caveauMEM Haiku brain message · via Telegram first turn bootstrap + recall + skills context + catalog injected context prompt + memory reply memory_episodic_log reply · via Telegram Nightly learning-review cron → distill / curate → Telegram report
The hook fires only on the first turn of a session; episodic logging and the nightly review keep Boris coherent without any manual context-pasting.

Give your agents a memory worth keeping.

Start free in the caveauAI portal, or book a call to scope a sovereign, governed memory deployment — and an agent like Boris — for your team.

Technical specifications & tools

Memory tool surface

memory_bootstrap
Called once per repo at session start — returns that repo’s rules, architecture, and deploy notes plus personal preferences and relevant secret key names.
memory_recall
Hybrid dense + BM25 search, expanded along the memory graph and fused with RRF, returning ranked results with source citations.
memory_context
Token-budgeted assembler that packs persistent, graph, scratch, and episodic memory into the model’s window without overflow.
memory_save / update / archive
Persist, revise, or retire a durable note, re-embedding only when content changes.
memory_scratch_set / get / delete
Ephemeral key/value working memory with a per-key TTL — never embedded, never searchable.
memory_episodic_log / recall
Append to and replay the time-scoped episodic timeline of actions and outcomes.
memory_feedback
Emit a learning signal (helpful / wrong / outdated / missing) that feeds the distill → curate loop.
memory_secret_set / get / list
Encrypted vault (AES-256-GCM); fetch by exact key only — never embedded, searchable, or logged.

Mechanism

Hybrid recall Dense embeddings + BM25 lexical, fused with Reciprocal Rank Fusion (k=60) and a private-scope boost.
Graph recall Top hits seed a per-client FalkorDB graph (mem_client_<id>); co-tag and supersedes neighbours are folded in via a second weighted RRF pass.
Context assembler Token-budgeted assembly with anti-starvation reserves across persistent, graph, scratch, and episodic tiers.
Memory tiers Persistent (embedded) + ephemeral scratch (1–7d TTL) + episodic log (30–90d TTL) + exact-key secret vault.
Scoping Per-client (tenant) isolation plus per-user vs shared “company” memory, enforced on every tier.
Learning loop Capture (memory_feedback) → distill (LLM-drafted candidates) → curate (human approve/reject). Only approved candidates are embedded.
Encryption Secret vault is AES-256-GCM at rest; exact-key fetch only, never embedded or searchable.
Token scopes MCP tokens carry memory.read / memory.write / secrets scopes — least privilege per host.
AI Chat — Beta Testing, Online Soon