README
¶
Hippocampus
Hippocampus provides human-like memory for digital data. It uses events with linked memories, each of which have their own significance rating on an open scale, reinforced through recall, and a sleep cycle to shed memories that are no longer worth keeping. It is a lossy data store by design, meant for long-term storage.
🔭 See it running — hippocampus-demo.com
📈 What forgetting costs you
A store that forgets is only worth having if what it keeps is what you turn out to need. That is measurable, so it has been measured — by replaying an agent workload fitted to a real corpus into a live instance and scoring the survivors against the standard cache-replacement baselines at the same store size:
Every access-based policy is statistically indistinguishable from random at retaining the memories that matter but are not touched often. LRU scores 20.2% against random's 19.9%; LFU manages 18.4%. Hippocampus scores 27.6% at the same store size, and +11.1 points over LRU at a larger one.
Importance is not in the access log, so a policy reading only the access log cannot see it. Method, baselines, the checks that stop it being circular, and the limitations: Retention quality.
📚 Documentation
The guides below cover the service itself; the components that ship around it are in the second table. If you are deciding rather than deploying, read Use cases & deployment modes first — its Worth knowing before you start section is the set of properties that shape what you can build on this.
Core
| Guide | Description |
|---|---|
| 🎬 Getting Started | Step-by-step build, initial config, and first gRPC/HTTP requests. |
| 📐 Use Cases & Patterns | Embedded vs. centralised topologies and data transfer strategies. |
| 🧠 Memory Consolidation | Deep dive on decay algorithms, capacity targets, and summarisation. |
| 🧙 Configuration wizard | Build a config and its deployment artefacts in the browser, with a live forgetting preview. |
| ⚙️ Configurability | Exhaustive key reference for TLS, auth, storage drivers, and listeners. |
| 🛠️ Operations & Deployment | Containers, Kubernetes, packages, sizing, backups, shutdown, and observability. |
| 🔒 Security | What is off by default, auth and role tiers, hardening checklist, and where content can leave. |
| 📈 Retention quality | What a bounded store keeps, measured against the standard cache-replacement baselines. |
| 📊 Performance Benchmarks | Throughput sweeps across SQLite, Postgres, and MySQL under heavy loads. |
| 🧪 Demonstrations | The hosted demo, plus worked scenarios using real-world data shapes and generators. |
| 🖥️ Web console | The console every instance serves at /ui — what each tab answers, and where its numbers come from. |
Tertiary
| Guide | Description |
|---|---|
| 🤖 MCP Server | Give an LLM host (e.g. Claude, ChatGPT, Gemini, etc) memory tools via the Model Context Protocol. |
| 🔌 Event Sourcing | Bridge NATS, MQTT, RabbitMQ, Kafka, or the Bluesky firehose in, storing each message as a memory. |
| 🚦 Ingestor | Stage data at the edge and promote completed events into a central store under CEL rules. |
| 💻 CLI | Drive a running service from the shell over either transport. |
| 🧬 Clients & Codegen | Generate a Python, TypeScript, or any-language client from the proto or OpenAPI document. |
| 📓 Obsidian Integration | Use Hippocampus as a memory layer for an Obsidian vault via the plugin or the MCP bridge. |
Directories
¶
| Path | Synopsis |
|---|---|
|
Package archive implements the export/import wire format shared by the S3 Export/Import RPCs: a gzip-compressed stream of length-delimited ArchiveRecord protos, header first.
|
Package archive implements the export/import wire format shared by the S3 Export/Import RPCs: a gzip-compressed stream of length-delimited ArchiveRecord protos, header first. |
|
cmd
|
|
|
config-wizard
command
Command hippocampus-config-wizard serves the configuration and deployment wizard: a browser-based, guided builder for a Hippocampus config.json and the deployment artefacts that carry it (Docker Compose, Kubernetes, systemd, or a plain binary run).
|
Command hippocampus-config-wizard serves the configuration and deployment wizard: a browser-based, guided builder for a Hippocampus config.json and the deployment artefacts that carry it (Docker Compose, Kubernetes, systemd, or a plain binary run). |
|
hippocampus
command
|
|
|
Package contract is a reverse proxy.
|
Package contract is a reverse proxy. |
|
demo
|
|
|
generator
command
The generator is a long-running load driver for the hippocampus service.
|
The generator is a long-running load driver for the hippocampus service. |
|
injector
command
Command injector seeds a Hippocampus instance with representative corporate events and memories through the HTTP/JSON gateway's ImportBatch endpoint (POST /v1/import/batch).
|
Command injector seeds a Hippocampus instance with representative corporate events and memories through the HTTP/JSON gateway's ImportBatch endpoint (POST /v1/import/batch). |
|
Package embed provides the optional text embedder that turns memory bodies and search queries into vectors, so memories can be found by meaning rather than by the words they happen to use.
|
Package embed provides the optional text embedder that turns memory bodies and search queries into vectors, so memories can be found by meaning rather than by the words they happen to use. |
|
Package observability installs the global OTEL tracer and meter providers, and serves the liveness/readiness endpoints an orchestrator probes.
|
Package observability installs the global OTEL tracer and meter providers, and serves the liveness/readiness endpoints an orchestrator probes. |
|
Package ratelimit implements the service's request throttling: a hierarchy of token buckets that admits a request only when every level that applies to it has a token to spend.
|
Package ratelimit implements the service's request throttling: a hierarchy of token buckets that admits a request only when every level that applies to it has a token to spend. |
|
Package search provides the optional secondary content-search index.
|
Package search provides the optional secondary content-search index. |
|
Package summarise provides the optional embedded-LLM summariser used to condense the memories of an event into a single summary.
|
Package summarise provides the optional embedded-LLM summariser used to condense the memories of an event into a single summary. |