VaporMemory
Self-hosted · recall for agents
A language model will repeat a two-year-old note as confidently as this morning’s. VaporMemory answers with text it can still stand behind: every result names the source revision it came from, reading it re-checks that hash, and the index records why it matched. When the file behind a memory changes, the old text stops being quotable until the index is rebuilt, and any review of it stops counting.
A result carries its source, its id and heading, and the SHA-256 of the source file it came from. Reading it re-reads the file and compares that hash before returning a word, so an answer is always traceable to something a person can open.
Drift, deletion and expired snapshots are detected when results are built. Those results are left out by default and the response says so, because a stale fact served confidently is the failure this exists to prevent.
A rating says how useful a memory is. A review is a separate record of the claims someone checked, the evidence and the date it lapses. Neither is inferred from the other, or from a file’s timestamp.
Each retrieval records the query, the terms that matched, keyword or semantic, the rank, and the agent, model and session that asked. Which memories actually get used stops being a guess.
Try it
A working model of the recall loop over five fictional notes. Search, read a source, change the file underneath it, send the same memory to one session twice, and have an agent draft a review. Everything runs in this page; nothing is sent anywhere.
Choose Read on a result.
Tokens are characters ÷ 4, an estimate.
Sample index ready: 5 notes, 6 passages, 2 sources.
Sources
A memory system that only reads one directory has to be told everything twice. VaporMemory indexes the places the answers already live, labels each with what it is worth, and never edits any of them.
A repository file is tracked working-tree text, which is not proof of what is deployed. A configuration file may not be the active one. An imported record is a snapshot with a collection time, not a live reading, and it expires within minutes. An offline encyclopedia is an edition, not the present tense.
Those sentences travel with the result, into the interface and into the tool output an agent receives, so the caveat arrives attached to the claim instead of living in a README nobody re-reads.
The notes folders are indexed whole; everything else is added explicitly — exact files, records, projects and pages — and nothing outside the configured roots is read. Known credential fields are redacted before anything is indexed.
How it works
Nothing here is a black box. Retrieval is keyword search fused with embeddings from a model on the same machine, and the index is one local SQLite file kept apart from the sources it describes.
Sources are split by heading and hashed, and the index refreshes itself a few minutes after the last run. A missing mount or a source that is suddenly empty aborts the refresh rather than emptying the index, because an empty index looks exactly like an answer of “nothing known”.
BM25 over full-text search and cosine similarity over local embeddings, fused by rank. When the embedding service is down the response says so and falls back to keyword search, rather than silently returning worse answers.
Reading a source re-reads the file and compares the hash. A mismatch is an error, not a warning, and the text is not returned.
Ratings and reviews are appended to a review log in the notes store, carrying the reviewer, each claim checked, the evidence and the date the review lapses.
Sessions
Every recall is attributed to the agent process that made it and, when the harness names one, to its session. A launcher can set the session and model in the agent’s environment, and VaporMemory reads them from the agent’s own process, so a recall through MCP, a hook or the command line lands on the same session.
Within a session, a memory that was already sent in full — same id, heading and hash — comes back as a bare reference for the next twelve hours. A new revision is sent again. A named session only ever matches itself, so a gateway hosting several chats does not suppress one conversation’s context because another already saw it.
Each call records how many results it returned, how many were repeats, the size of the response and how long it took. Usage reports turn that into recalls and an estimated token count per agent, model and session — characters divided by four, and labelled as an estimate.
VaporAgent launches every agent with its session id in the environment and shows the result on the agent card as ◉ 5 · ~2.4k: recalls, then estimated tokens. Projects can pin up to four source snapshots that task prompts and handoffs quote, and Stack & usage shows a week of recall by agent.
See it in VaporAgentAgents
Agents reach the index over the Model Context Protocol, with a read-only mode that exposes ten of the seventeen tools. They can search, read a verified source, work through a review queue and submit an assessment — attributed to the agent, never blended into a person’s.
From the interface you can hand one memory to Claude Code, Codex or Hermes and pick the model. It runs with no tools, sees the source, its last reviews and a few related memories, and proposes a review that stays a draft until you confirm it. You can also run one agent over every memory that is due or unreviewed; that run records drafts for you to accept or discard, or — only if you start it that way — saves them as the agent’s own reviews, never under a person’s name. A run that keeps failing stops and says why.
The rules are enforced after the model answers rather than asked for in the prompt. A draft made without live checks cannot return “verified”. A claim called supported that cites none of the material it was shown is downgraded to unresolved, and confidence without evidence is dropped. Each correction is shown next to the draft.
Agreement between two notes is corroboration, not proof — the review format has somewhere to say that, and the interface does not round it up to a tick.
Usage
Every recall records what it returned and why. That turns a memory store from a pile you hope is working into something you can audit: the queries that pull each note, which caller asked, and — sorted by use — the notes nothing has needed.
| Caller | Recalls | Retrievals | Memories | Est. tokens |
|---|---|---|---|---|
| claude · large model · mcp | 212 | 640 | 96 | ~61k |
| hermes · local model · hook | 188 | 410 | 54 | ~38k |
| operator · dashboard | 63 | 150 | 48 | ~19k |
A retrieval means a memory was returned to a caller. It is not evidence that the caller read it, used it or believed it, and the reports say so rather than letting a popularity count pass for importance.
Explore
Memories are drawn as a rotating three-dimensional graph. Solid links are explicit references one note makes to another. Dotted links are term similarity, computed from shared vocabulary — a lexical association, never an asserted relationship between facts.
Colour is link count and nothing else. It is not confidence, importance or truth, and the legend says which it is, because a heatmap that means “popular” is very easily read as “reliable”. Review state shows separately, as a worn rim on nodes whose quality is in doubt.
Selecting a node pauses the rotation and eases the pivot onto it; clearing the selection returns to the cluster. Label density is a control rather than a guess, and focus changes are immediate when the browser asks for reduced motion.
An offline encyclopedia and documentation library — tens of millions of pages across dozens of archives — is searched in place through each archive’s own full-text index, in one query per catalogue language rather than one per archive. Nothing is copied into the memory store to make it searchable.
A page becomes a memory only when someone captures it — up to fifty per archive — and then it is a fixed revision like any other source: hashed, rateable and reviewable. The rest of the library stays searchable and stays out of the review queue.
Limits
A memory system that oversells itself is worse than none, because the confidence is what gets acted on. These are the boundaries, stated where they are easy to find.
A matching hash proves the text has not changed since it was indexed. It says nothing about whether the text was ever right, and nothing about whether it is right now.
Verification is something a reviewer does with other evidence and records here. No agent draft can mark a memory verified, and a lapsed review reverts to unverified rather than quietly persisting.
Two notes agreeing may mean one was copied from the other. Similarity links and related sources are offered as candidates to check, never as confirmation.
The agent’s process is observed, but the agent, model and session names are what each client said. Nothing in the server can confirm them, so the reports carry that caveat instead of presenting the breakdown as attested fact.
There is no hosted service and no account. It runs on your own machine, the interface and embeddings stay on the loopback interface, and remote access is whatever single sign-on you already put in front of it.
Indexed files are read, never written. Ratings and reviews are appended through the notes tool that already owns that folder, so removing VaporMemory leaves the source material exactly as it was.
Questions
It uses vectors, but the index is a single SQLite file holding the text, the chunk boundaries and the embeddings together. Keyword search does the work when the embedding service is down, which for a memory you rely on during an outage is the case that matters most.
Because then the record of what it knows is written by the same thing that will later cite it. Sources are chosen deliberately, reviews are attributed to whoever made them, and an agent’s assessment is stored as an agent’s assessment.
Until the index is refreshed — automatically, within minutes — recall leaves the memory out and reading it fails its hash check. After the refresh the new text is quotable, and any review attached to the old revision stops counting, because it was a statement about text that no longer exists.
Retrieval, embeddings, the index and the interface are local. Outbound traffic goes to the systems you add as sources, read-only, and — only if you ask an agent to draft reviews — to whichever model provider sits behind the agent command you pick, which receives the text being reviewed.
The running instance holds a private homelab’s documentation, so it is not open to the internet, and this page uses drawings and sample notes rather than screenshots of it. The demo above runs the same recall rules over fictional data. The source is not public yet.