ELF

Evidence-linked fact memory for agents.

What Is ELF?

ELF is a memory service for LLM agents that stores short, evidence-linked facts and retrieves them with chunk-first hybrid search. Postgres with pgvector is the source of truth for notes and embeddings. Qdrant is a derived, rebuildable index for fast candidate retrieval. ELF can also persist evidence-bound entity/relation facts and optionally attach them as relation_context in search explain output. ELF exposes both HTTP and MCP interfaces.

Project Goals

• Improve effective context usage with compact memory retrieval instead of replaying long history.
• Preserve correctness over time with update and lifecycle semantics, not append-only memory.
• Keep memory behavior auditable with deterministic boundaries, evidence, and replayable traces.
• Enable safe multi-agent collaboration through explicit scopes and sharing controls.
• Make quality measurable with repeatable evaluation and regression checks.

Why Choose ELF

• Evidence-linked memory with strict provenance requirements.
• Deterministic add_note and LLM-driven add_event separation.
• Postgres source-of-truth plus rebuildable retrieval index.
• Chunk-first hybrid retrieval with expansion and rerank controls.
• Multi-tenant scoped APIs for service-style integration.
• Evaluation tooling (elf-eval) for retrieval quality and replay analysis.

Quickstart

Use the canonical setup guide:

• docs/guide/getting_started.md

Fast path:

cp elf.example.toml elf.toml
psql "<dsn from elf.toml>" -f sql/init.sql
./qdrant/init.sh
cargo run -p elf-worker -- -c elf.toml
cargo run -p elf-api -- -c elf.toml
cargo run -p elf-mcp -- -c elf.toml

Architecture

flowchart TB
  subgraph Clients
    Agent[Agent / App]
    MCPClient[MCP Client]
    Eval[elf-eval]
  end

  subgraph Services
    API[elf-api]
    MCP[elf-mcp]
    Worker[elf-worker]
  end

  subgraph Storage
    PG[(Postgres with pgvector<br/>source of truth)]
    Qdrant[(Qdrant<br/>rebuildable index)]
  end

  subgraph Providers
    Embed[Embedding Provider]
    Rerank[Reranker]
    Extractor[LLM Extractor]
  end

  Agent -->|HTTP| API
  MCPClient -->|MCP| MCP
  MCP -->|HTTP| API
  Eval -->|HTTP| API

  API -->|add_note| PG
  API -->|memory_ingest_decisions| PG
  API -->|add_event| Extractor
  Extractor -->|evidence-bound notes| API
  API -->|persist| PG
  PG -->|outbox| Worker
  Worker -->|index chunks, dense and BM25| Qdrant

  API -->|search| Expand{Expand mode<br/>off, always, dynamic}
  Expand -->|original| Embed
  Expand -->|LLM variants| Extractor
  Extractor -->|expanded queries| Embed
  Embed -->|dense vectors| Qdrant
  API -->|BM25 query| Qdrant
  Qdrant -->|RRF fusion candidates| API
  API -->|scope/TTL filter| PG
  PG -->|notes| API
  API -->|rerank and recency| Rerank
  Rerank -->|scores| API
  API -->|top-k| Agent

Loading

Comparison

Quick comparison snapshot (objective/high-level). This table compares capability coverage, not overall project quality.

Capability	ELF	OpenViking	mem0	qmd	claude-mem	memsearch
Local-first self-hosted workflow	✅	✅	✅ (OpenMemory)	✅	✅	✅
MCP integration	✅	—	✅ (OpenMemory)	✅	✅	⚠️
CLI-first developer workflow	—	✅	—	✅	⚠️	✅
HTTP API service surface	✅	✅	✅	⚠️ (MCP Streamable HTTP)	✅	—
Query expansion or query rewriting	✅	✅	⚠️	✅	—	—
LLM reranking stage	✅	⚠️	⚠️	✅	—	—
Hybrid dense + sparse retrieval	✅	✅	⚠️	✅	✅	✅
Progressive disclosure style retrieval	✅	✅	—	—	✅	⚠️
Evidence-bound memory writes	✅	—	—	—	—	—
Deterministic and LLM-ingestion boundary	✅	⚠️	⚠️	—	—	—
Source-of-truth + rebuildable derived index	✅	✅	⚠️	⚠️	⚠️	✅
Hierarchical/recursive retrieval strategy	⚠️ (in progress)	✅	⚠️	⚠️	⚠️	⚠️
Progressive context loading (L0/L1/L2 style)	⚠️ (in progress)	✅	⚠️	—	⚠️	—
Built-in web memory inspector/viewer	—	—	✅ (OpenMemory)	—	✅	—
Hosted managed option	—	—	✅	—	—	—
Multi-tenant scope semantics	✅	⚠️	✅	—	—	—
TTL/lifecycle policy controls	✅	⚠️	✅	—	⚠️	—
Graph memory mode	⚠️ (graph-lite: structured relations persisted; optional search relation_context)	⚠️ (URI-link relations)	✅ (optional)	—	—	—

Legend: ✅ built-in and documented; ⚠️ partial, optional, or in-progress; — not a first-class documented capability.

Project signature strengths (what each does especially well):

Project	Signature strengths	Potential ELF adoption value
ELF	Evidence-bound writes, deterministic ingestion boundary, SoT + rebuildable index, eval tooling	Keep as core differentiators while extending retrieval and UX
OpenViking	Filesystem-like context model (viking://), hierarchical retrieval, staged retrieval trajectory	Improve query planning, recursive retrieval, and explainable stage outputs
mem0	Broad ecosystem (SDK + hosted + OpenMemory), multi-entity scope, lifecycle + optional graph memory	Strengthen event/history APIs and additive graph context channel
qmd	High-quality local retrieval pipeline (query expansion + weighted fusion + rerank), strong CLI/MCP workflow	Borrow transparent routing/fusion knobs and local debugging ergonomics
claude-mem	Progressive disclosure UX, automatic capture loop, practical local viewer/inspection workflow	Add operator-facing viewer/status/trace surfaces for faster tuning
memsearch	Markdown-first canonical store, incremental reindex, practical hybrid retrieval	Reinforce ingest/index consistency and developer-friendly local workflows

Detailed comparison, mechanism-level analysis, and source map:

• Detailed External Comparison
• Research Projects Inventory

Snapshot date in that document: February 17, 2026.

Documentation

• Start here: docs/index.md
• Operational guide index: docs/guide/index.md
• Research index: docs/research/index.md
• Specifications: docs/spec/index.md
• System contract: docs/spec/system_elf_memory_service_v2.md
• Ingest policy: policy_decision values (remember, update, ignore, reject) are returned for each note result in add_note and add_event.
• All ingest decisions are also written to memory_ingest_decisions with policy inputs and thresholds for auditability.
• Evaluation guide: docs/guide/evaluation.md
• Integration testing: docs/guide/integration-testing.md

Development

cargo make fmt
cargo make lint
cargo make test

For integration and E2E workflows, use docs/guide/getting_started.md and docs/guide/integration-testing.md.

Support

If you find this project helpful and want to support its development:

• Ko-fi: https://ko-fi.com/hack_ink

• Afdian: https://afdian.com/a/hack_ink

• Bitcoin: bc1pedlrf67ss52md29qqkzr2avma6ghyrt4jx9ecp9457qsl75x247sqcp43c

• Ethereum: 0x3e25247CfF03F99a7D83b28F207112234feE73a6

• Polkadot: 156HGo9setPcU2qhFMVWLkcmtCEGySLwNqa3DaEiYSWtte4Y

Appreciation

• The Rust community for continuous support and development of the ecosystem.

License

^{Licensed under GPL-3.0.}