gigabyte22/elephant

Long-term memory for AI agents, in a single service. Elephant gives your
agent orchestrator durable, searchable memory backed entirely by Neo4j — its
native vector, full-text, and temporal capabilities mean there is no separate
vector database, SQL store, or queue to operate.
Hybrid GraphRAG recall — vector + full-text search fused with reciprocal
rank fusion, optional LLM reranking, and optional HippoRAG-style
personalized PageRank over the entity graph.
Bi-temporal facts — every fact splits valid time (validFrom /
validTo: when the claim held in the world) from transaction time
(recordedAt: when Elephant wrote it). Supersede closes the old claim at
event time; decay and prune use transaction/access time so backfilled
episodes stay sane. GET /timeline is valid-time as-of.
Dreaming — a scheduled consolidation job (default: nightly) extracts
facts from raw episodes, deduplicates semantically, promotes high-importance
facts to insights, consolidates fragment facts about one entity into a
canonical fact, resolves duplicate entities into :SYNONYM links, builds
entity relations, and prunes stale memories along an Ebbinghaus-style decay
curve.
Scoped memory — four scope axes (agentId, sessionId, projectId,
userId), each configurable to boost, filter, strict, shared, or
ignore at recall time.
Prospective memory — :Intention nodes record forward-looking
commitments ("remind me before the registration lapses"). Elephant is
pull-only and never fires them; an external scheduler owns the clock.
Markdown vault — with OKFENABLED, research and knowledge documents
project one-way into plain markdown files with YAML frontmatter, readable by
Obsidian, grep, or git. The graph stays the source of truth.
Inspector dashboard — a built-in web UI for browsing the graph, facts,
timeline, dream runs, and audit log.
## How it works
Your orchestrator POSTs raw conversation episodes; Elephant chunks and
embeds them. Writes never wait on a model: the summary of a long transcript
and the contradiction check on a directly-written fact both happen in the
dream cycle, not in the request. Extraction turns episodes into facts and
preferences, which link to auto-upserted entities — the hubs of the
knowledge graph. Recall queries the whole
structure hybridly and returns a ranked, scoped working set. Everything is
auditable: fact creation, supersession, and deletion all record audit events
with revision snapshots.
v1.2 adds knowledge documents (file ingestion with blob storage),
versioned procedures (skills with success stats), project-scoped
research notes, a pluggable working state KV, and the audit API.
See SPEC.md for the full data model and EXPECTED.md
for the complete API contract. INTEGRATION.md walks through
wiring an orchestrator against the service — including a write-tier decision
tree (which API for facts vs observations vs research vs state).
## Quickstart
Requirements: Node ≥ 22, pnpm, Docker.
bash
# 1. Configure
cp .env.example .env
# Set MEMORYSERVICETOKEN, NEO4JPASSWORD, and LLM/embedding keys
# (ANTHROPICAPIKEY and/or OPENAIAPIKEY; EMBEDDIM must match your
# embedding model — see comments in .env.example).
# 2. Start Neo4j (community image with APOC + GDS plugins). Compose reads