# FluctlightDB

FluctlightDB is an embedded memory database for AI agents. experience() writes, activate() recalls from a cue, checkpoint() keeps it. Open source, beta.

Status: beta. Licence: MIT or Apache-2.0.

Install: `pip install "fluctlightdb[native]"`

## The contract

### experience() — Write what happened

A tool result, a user fact, an observation. It carries context, salience and provenance, not just text. Nothing is extracted from a transcript later; the agent records the moment it happens.

### activate(cue) — Recall from a cue

Full-text search, vector neighbours and graph spreading activation are fused inside one call. The question is not "what is nearest" but "what should this cue bring back".

### checkpoint() — Survive the restart

A write-ahead log and atomic checkpoints put the brain directory on disk. Crash recovery is exercised in CI with SIGKILL mid-write and torn WAL tails.

## Integrations

- LangChain: FluctlightMemory, chat history
- LlamaIndex: FluctlightLlamaMemory
- OpenAI Agents SDK: remember and search handlers
- MCP: Cursor, Claude and Codex
- Docker: ghcr.io/voxmastery/fluctlightdb
- Node: over HTTP from fluctlight-serve

## Stable surface

- connect_embedded(), connect_agent() and the other connect_* entry points
- experience(), activate(), checkpoint(), recall()
- The v4 brain directory on disk
- POST /api/v1/experience and /api/v1/activate

## Benchmarks

Conditions: Maintainer-reported; Frozen July 2026; Harnesses open; No independent reproduction yet.

- 96.8% — LoCoMo evidence recall (at k=150 · 10 conversations, 1,982 questions · MiniLM-384)
- 72.6% — LoCoMo evidence recall (at k=5 — the operational number)
- 97.6% — LongMemEval-S session recall (at k=8 · 488 of 500)
- 97.4% — LongMemEval end-to-end QA (487 of 500 · locked run, gpt-4o reader and judge)
- 0.646 — BEIR SciFact nDCG@10 (against Chroma 0.645 in a shared harness)

## Retracted, not a current claim

99.0% (LoCoMo evidence recall at k=150) is retracted. The old figure expanded every retrieved turn by three neighbours on each side, then counted neighbours the engine never retrieved. A plain BM25 baseline also reaches about 99% under that protocol, so it distinguished nothing. It is not the headline any more, and it is not a number we will defend.

## A limit

Offline, recall is lexical: a cue has to share tokens with what was stored. Paraphrase recall needs a semantic vector from an embedder you bring.

## Read next

- [Install](/install)
- [Quickstart](/quickstart)
- [Documentation](/docs)
- [Questions](/faq)
- [Compared](/compare)
- [Benchmarks](/benchmarks)
- [Facts](/facts.json)
- [Source](https://github.com/voxmastery/FluctlightDB)
- [Package](https://pypi.org/project/fluctlightdb/)
- [Paper](https://arxiv.org/abs/2608.12365)