Technical whitepaper · v1.1
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
Every derived fact remains linked to the source record that supports it.
Hard scope
Every recall is constrained by tenant, owner, and optionally one named brain.
Many-to-many truth
One source can yield many facts, and one fact can be supported by many sources.
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.
Core invariant: derived memory can become richer than the source, but it must remain attributable to the source and recallable only inside the user’s chosen 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 linked directly to its source record.
Layer 4
Belief
Independent evidence consolidates into a current understanding without replay inflation.
Stable content fingerprints version source records. An unchanged replay refreshes last-seen state without paying again for embeddings or AI extraction; changed content advances the source version and is processed again. This makes retries idempotent and keeps ingestion cost proportional to change rather than corpus size.
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 identity, content fingerprint, version, last-seen time, and object metadata | Keeps the original provenance and detects whether a source is new, changed, or an unchanged replay. |
| 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, evidence text, and direct source link | Lets one source support many statements while each statement remains attributable to its exact source record. |
| Belief ledger | Canonical claims, independent-source counts, confidence, validity windows, and supersession status | Lets many independent sources support one current understanding without counting the same replay twice. |
| Graph + synapses | Typed node relationships, weights, reinforcement counts, half-lives, and decay state | Adds associative structure and a learned signal from repeated use. |
04 · Evidence reconciliation
Agreement grows confidence. Replays do not.
Facts and beliefs form a many-to-many evidence graph. A meeting, message, or note can support several facts; the same canonical claim can also be supported by several independent records and connector services.
Confidence is reconciled from distinct evidence identities, source diversity, positive support, and contradiction. Reprocessing the same record updates its evidence instead of increasing the source count.
When a current-state claim changes, a newer well-grounded claim can supersede the older active state while preserving its validity window and evidence trail. Removing one connector removes only its contribution; shared beliefs survive when another source still supports them.
05 · 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.
06 · 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.
07 · 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.
- Independent-source identities prevent retries or repeated imports from manufacturing confidence.
- Removing one connector contribution preserves a shared fact or belief when another source still supports it.
- 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.
08 · 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.