'||                                 
 ||      ''                         
 ||''|,  ||  '||''|, '||''|, .|''|, 
 ||  ||  ||   ||  ||  ||  || ||  || 
.||  || .||.  ||..|'  ||..|' `|..|' 
              ||      ||            
             .||     .||            

🦛 The memory graph for AI agents that improves whilst it sleeps.
Background passes infer links, resolve contradictions, and weight sources. Server, embedded, or browser via WASM.

---

What it is

Hippo extracts entities and relationships from natural language, stores them in a typed graph, and runs background passes that infer new edges, write supersession relationships when sources disagree, and update per-source accuracy.

Reads use an iterative loop: /ask requests additional context from the graph until it has enough to answer.

        write something                         ┌──────────────┐
              │                                 │   Dreamer    │
              ▼                                 │  (background)│
       ┌─────────────┐                          │              │
       │  /remember  │                          │  • Linker    │
       └──────┬──────┘                          │  • Inferrer  │
              │                                 │  • Reconciler│
              ▼                                 │  • Consolid. │
       ┌─────────────┐ ◄────── reads ────────── └──────┬───────┘
       │  the graph  │ ─────── writes ─────────────────┘
       └──────┬──────┘
              │
              ▼
       ┌─────────────┐
       │    /ask     │   ranking by salience + credibility,
       │             │   filtered by supersession
       └─────────────┘

Design

The Dreamer is the background pass. It walks the graph and emits append-only actions: links between previously unconnected entities, edges inferred from existing structure, supersedes edges when two sources disagree, and consolidation of episodic facts into semantic patterns. See docs/DREAMS.md.

Writes are append-only. Contradictions produce a supersedes edge; the original is retained and filtered out at read time by default. retract and correct are available for explicit removal.

Sources carry an accuracy score updated as contradictions resolve. Edges carry a salience score incremented on each retrieval.

Backends: SQLite, Postgres, in-memory, FalkorDB, Qdrant. The same Rust core compiles to wasm32-unknown-unknown.

Architecture

                  ┌───────────────────────────────────────────┐
                  │              GraphBackend                 │
                  │  (trait — implemented by 5 backends)      │
                  ├───────────────┬───────────┬───────────────┤
                  │ InMemory      │ SQLite    │ Postgres      │
                  │ (test, WASM)  │ (default) │ (multi-node)  │
                  ├───────────────┼───────────┼───────────────┤
                  │ FalkorDB (Cypher)         │ Qdrant (vec)  │
                  └───────────────────────────┴───────────────┘
                              ▲
                              │
       ┌──────────────────────┼──────────────────────┐
       │                      │                      │
   pipeline::             pipeline::             pipeline::
   remember               ask                    dreamer
   (write)                (read)                 (background)
       │                      │                      │
       │                      ▼                      ▼
       │              iterative LLM loop      WorkerPool drives
       │              over the subgraph       Linker/Inferrer/
       │                                      Reconciler/Consolid.
       ▼
   plan → enrich → execute
   (LLM extracts ops; graph
    enriches; ops applied)

Quick start

As a server

# 1. Set credentials
export ANTHROPIC_OAUTH_TOKEN=...      # or ANTHROPIC_API_KEY

# 2. Choose a backend (default: in-memory)
export GRAPH_BACKEND=sqlite
export SQLITE_PATH=./hippo.sqlite

# 3. Enable production safety
export HIPPO_AUTH=true
export HIPPO_RATE_LIMIT=true

# 4. Run
cargo run --release --bin hippo

Using the TypeScript SDK

import { HippoClient } from "@dcprevere/hippo-sdk";

const hippo = new HippoClient({
  baseUrl: "http://localhost:21693",
  apiKey: process.env.HIPPO_API_KEY,
});

// Write
await hippo.observe({ statement: "Alice works at Acme as a lawyer" });

// Read
const { answer } = await hippo.recall({ question: "Where does Alice work?" });

// Trigger one dream pass and inspect what changed
const report = await hippo.dream();
console.log(report); // { facts_visited, links_written, supersessions_written, ... }

// Explicitly correct an error
await hippo.correct({
  edge_id: 42,
  statement: "Alice works at Acme as a doctor",
  reason: "extraction error — original transcript said doctor",
});

In the browser (WASM)

import init, { Hippo } from "@dcprevere/hippo-wasm";

await init();
const hippo = new Hippo(JSON.stringify({
  api_key: localStorage.getItem("openai_key"),
  model: "gpt-5.4",
}));

await hippo.remember("I prefer cycling to driving");
const answer = await hippo.ask("How do I get around?");

API surface

Core verbs

Verb	HTTP	What it does
observe / remember	POST /remember	Extract entities and facts from a natural-language statement; resolve against existing entities; write append-only edges.
recall / ask	POST /ask	Iteratively gather context from the graph, return an LLM answer plus the supporting facts.
context	POST /context	Raw subgraph for a query, no LLM synthesis.
dream	POST /maintain	Trigger one dream pass; returns a DreamReport with counts. Runs continuously in the background by default.
retract	POST /retract	Explicit user/agent destructive removal of an edge with audit reason. Distinct from autonomous supersession.
correct	POST /correct	Convenience: retract + observe in one call.

Auxiliary

Verb	HTTP	What it does
Provenance	GET /edges/:id/provenance	Supersession chain for an edge — what it replaced, what replaced it.
Graph dump	GET /graph	Full graph (entities + active edges + invalidated edges).
Events	GET /events	Server-sent events stream of graph mutations.
Health	GET /health	Liveness check.
Metrics	GET /metrics	Prometheus exposition.

Full schemas: see docs/openapi.yaml.

Backend support

Backend	Status	Best for	Dreamer support
SQLite	✅ Stable	Single-node, embedded, dev	Full (reference impl + parity tests)
Postgres	✅ Stable	Multi-node, managed cloud	Full (additive CREATE TABLE IF NOT EXISTS migrations)
In-memory	✅ Stable	Tests, WASM	Full
FalkorDB	⚠️ Experimental	Cypher graph queries	Implemented; parity tests not yet automated
Qdrant	⚠️ Limited	Vector-first deployments	Partial (revisit-window is a no-op) — not recommended for production Dreamer use

See docs/CONFIG.md#backend-readiness-matrix for details.

Comparison

	Hippo	Mem0 v3	Zep / Graphiti	Supermemory	Letta
Contradiction handling	Background supersedes	None (ADD-only)	Write-time invalid_at	Write-time isLatest	App-defined
Background graph processing	✅	❌	Ingest-time community detection	Documented, not in OSS	❌
Inference of new edges	✅	❌	❌	Documented, not in OSS	❌
Salience-on-use ranking	✅	❌	❌	❌	❌
Append-only writes	✅	n/a	❌	❌	❌
Browser (WASM)	✅	❌	❌	❌	❌
Iterative reads	✅	❌	❌	❌	Via agent loop

Notes:

• Mem0 v3 (April 2026) removed the v2 graph backend in favour of a pure vector + entity-sidecar model.
• Supermemory's Derives and Automatic Forgetting are documented but not present in any source available for inspection.

Configuration

Environment variables and hippo.toml cover the same surface. See docs/CONFIG.md for the full matrix.

Quick prod template:

[graph]
backend = "postgres"
name = "hippo_prod"

[graph.postgres]
url = "postgres://hippo:secret@db.internal:5432/hippo"

[auth]
enabled = true

[rate_limit]
enabled = true
requests_per_minute = 60

[pipeline.tuning]
dreamer_worker_count = 2
dreamer_max_units = 200
dreamer_max_tokens = 100000

Production checklist

• Backend is SQLite or Postgres (not Qdrant for Dreamer use).
• HIPPO_AUTH=true; HIPPO_INSECURE and ALLOW_ADMIN are unset.
• HIPPO_RATE_LIMIT=true with a sensible HIPPO_RPM.
• TLS terminated either by hippo (HIPPO_TLS=true) or a fronting proxy.
• Dreamer cost ceilings set in hippo.toml.
• LLM credentials set via *_OAUTH_TOKEN or *_API_KEY.
• Container runs as non-root (the bundled Dockerfile already does this).

Project layout

hippo/
├── src/
│   ├── backends/           # GraphBackend impls (in_memory, sqlite, postgres, qdrant, falkor)
│   ├── pipeline/
│   │   ├── ask.rs          # iterative read path
│   │   ├── remember.rs     # plan → enrich → execute
│   │   ├── maintain.rs     # housekeeping + drives the Dreamer
│   │   └── dreamer/        # Dreamer trait, WorkerPool, Linker/Inferrer/Reconciler/Consolidator
│   ├── llm/                # LlmClient + RetryingLlm decorator
│   ├── http/               # axum router + handlers
│   └── ...
├── hippo-api/              # shared request/response types (used by SDKs and server)
├── hippo-wasm/             # wasm-bindgen wrapper for in-browser use
├── sdks/typescript/        # @dcprevere/hippo-sdk
├── docs/
│   ├── DREAMS.md           # the Dreamer architecture
│   └── CONFIG.md           # full config reference + backend matrix
└── tests/                  # 450+ unit + contract + idempotency tests

Building & testing

# Native build + unit tests
cargo build --release
cargo test --tests              # ~450 tests, no network needed

# WASM build
cargo check --target wasm32-unknown-unknown --manifest-path hippo-wasm/Cargo.toml

# Lints (CI runs these with -D warnings)
cargo clippy --all-targets -- -D warnings
cargo fmt --check

# Integration / eval tests (require LLM credentials, gated with #[ignore])
cargo test --tests -- --ignored

CI runs unit tests + clippy + fmt on every PR; the eval suite runs nightly via .github/workflows/eval.yml.

Documentation

• docs/DREAMS.md — the Dreamer architecture, design decisions, and shortlist of must-have features.
• docs/CONFIG.md — full env-var matrix, backend readiness, production checklist.
• docs/openapi.yaml — HTTP API spec.

Licence

Hippo is not open source. The repository is published source-available so the implementation can be read, audited, and reasoned about, but there is no permissive licence — you may not redistribute, modify, or use the code in your own projects without an explicit written agreement.

If you'd like to use hippo in a product, get in touch.