Technical whitepaper · v1.0
How a brain becomes recallable.
hippocampOS is not a chat-history bucket and not a flat vector store. It is a brain-scoped evidence system that converts source records into searchable memories, grounded facts, evolving beliefs, and reinforced associations.
Evidence first
Original source identity and provenance remain attached to derived memory.
Hard scope
Every recall is constrained by tenant, owner, and optionally one named brain.
Many signals
Words, vectors, facts, beliefs, time, graph weight, and prior use cooperate.
01 · Definition
A brain is a boundary, not a blob.
A named brain is the product identity for one memory graph. The graph belongs to one tenant and one owner, and its identifier follows source records through ingestion, processing, storage, and recall. A “Work” brain and a “Home” brain can therefore share infrastructure without sharing retrieval context.
The Master Brain is an aggregate view across brains; it is not a loose global bucket. A normal brain-scoped request adds the graph identifier to every candidate query. Cross-brain recall happens only when the caller explicitly selects the aggregate scope.
02 · Encoding pipeline
From a source event to durable memory.
Layer 1
Source
Email, selected photo, free-form note, file, meeting, or external record.
Layer 2
Node
Compact title, summary, metadata, body signal, category, graph hints, and embedding.
Layer 3
Fact
A grounded subject–predicate–object statement with confidence and time.
Layer 4
Belief
Repeated evidence consolidates into a current, provenance-backed understanding.
Embeddings are created from the memory title, summary, gist, topics, entities, graph anchors, and a bounded body excerpt using OpenAI’s text-embedding-3-small model. If embedding generation is unavailable, lexical, fact, belief, and history paths still operate.
03 · What is stored
Five layers, five different jobs.
Storing everything in one representation creates brittle memory. The raw record is good evidence, the vector is good for similarity, the fact is good for precision, and the belief ledger is good for change over time.
| Layer | Stores | Why it exists |
|---|---|---|
| Source evidence | Connector rows and object metadata | Keeps the original provenance, source identifiers, sync state, and deletability boundary. |
| Memory nodes | Compact title, summary, metadata, strength, status, and a 1,536-dimensional embedding | Provides the searchable representation of an email, document, conversation, photo, or note. |
| Memory facts | Subject, predicate, object, confidence, time, validity, polarity, and evidence text | Turns source content into grounded statements without severing the link to evidence. |
| Belief ledger | Canonical facts, confidence, evidence counts, validity windows, and supersession status | Represents the system’s current understanding while retaining older contradictory states. |
| Graph + synapses | Typed node relationships, weights, reinforcement counts, half-lives, and decay state | Adds associative structure and a learned signal from repeated use. |
04 · Recollection
Recall is a race between complementary cues.
01
Understand the cue
The query is normalized and, in search mode, analyzed for intent, entities, concepts, providers, domains, and whether current web or location context is required.
02
Open parallel recall paths
hippocampOS searches vector similarity, lexical and recent source memories, distilled facts, active beliefs, and relevant query history at the same time—always inside the selected tenant, user, and brain scope.
03
Merge by evidence identity
Candidates collapse around their source memory-node ID. Fact matches enrich their source; beliefs can outrank a weaker raw record; duplicate paths do not become duplicate context.
04
Score and rerank
Title, summary, topics, people, organizations, graph anchors, body text, vector similarity, fact evidence, belief confidence, memory strength, and live synaptic weight contribute signals. Spam, weak provider matches, and degraded memories are penalized.
05
Return compact, grounded context
Only the highest-ranked hits are shaped into a small evidence bundle. Search can synthesize an answer; MCP recall can return context alone. Both preserve source IDs and trace metadata.
06
Reinforce useful paths
Recalled nodes and their connected synapses are strengthened, and the query is stored as history. Repetition therefore improves accessibility without rewriting the underlying source evidence.
05 · Remembering and forgetting
Use strengthens access. It does not rewrite history.
Current deployment status · Disabled
Neural degeneration is implemented, but it has been disabled for now. The background degeneration path is not actively fading or archiving user memories; stored memories remain recallable unless the user explicitly deletes them.
A successful recall updates the selected node’s memory strength and reinforces connected synapses. Synaptic weight is time-aware: where a half-life is configured, the effective contribution decays before new reinforcement is added.
If re-enabled in the future, neural degeneration would move weak memories through healthy, fading, degraded, and archived states. Synapses would lose effective weight according to their configured half-life, while node strength would combine remaining associative weight with time since the memory was last reinforced. Recall would strengthen useful paths again.
Pinned memories and system or user identity nodes are protected from degeneration. An archived node leaves normal retrieval and an archived synapse is pruned from traversal, but neither action deletes the source evidence, distilled facts, belief ledger, or provenance links.
The feature remains reversible. Disabling it restores affected nodes to healthy, recallable state, clears archive markers, and unprunes synapses in the same database transaction as the setting change. The implementation is retained for controlled future evaluation, not active forgetting today.
06 · Safety properties
Memory must know when not to speak.
- Tenant, owner, and brain filters are applied before ranking—not after context is assembled.
- Beliefs retain evidence links and validity windows, so a current claim can be traced and an older claim can be marked superseded.
- Irrelevant-memory guards can return no private context and recommend live web or location context instead.
- Derived summaries and AI facts are probabilistic; high-impact decisions should return to the source evidence.
07 · Evidence
Architecture is a claim. Benchmarks test it.
The current public evaluation measures whether the correct evidence is retrieved, not whether a language model writes a correct final answer. The benchmark report publishes both strong areas and failure categories.