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
There's a live instance at hippocampus-demo.com with nothing to
install. To watch forgetting happen locally, ./demo/run.sh from a clone runs the service and a
load generator with the decay clock compressed, so a cycle plays out in minutes rather than days.
Install
brew install fastbean-au/tap/hippocampus && brew services start hippocampus
Or a .deb/.rpm, the container image, a release binary, or go build — they're all one command
each, and they're all on the install page. From there,
Getting started covers the first requests and the configuration to grow
from.
What forgetting costs you
A store that forgets is only worth having if what it keeps is what you turn out to need. That's measurable, so it's 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 isn't in the access log, so a policy reading only the access log can't see it. Method, baselines, the checks that stop it being circular, and the limitations are all in Retention quality.
Documentation
The documentation index is the map — it's arranged by what you're trying to do, and it covers the deployment artefacts and the integration subprojects as well as the guides. Four worth naming here:
- Use cases & deployment modes — start here if you're deciding rather than deploying. The Worth knowing before you start section is the set of properties that shape what you can build on this.
- Memory consolidation — how it decides what to forget: the value model, the six decay algorithms, and the capacity axes.
- Configurability — the exhaustive key reference.
- Security — everything is off by default, so anything reachable beyond localhost needs a deliberate pass over this page.
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 notify provides the optional outbound callback sink: the component that tells an external system that Hippocampus has forgotten something, that a sleep cycle has finished, or - the one kind that speaks before the fact - that a cycle is about to forget something.
|
Package notify provides the optional outbound callback sink: the component that tells an external system that Hippocampus has forgotten something, that a sleep cycle has finished, or - the one kind that speaks before the fact - that a cycle is about to forget something. |
|
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. |