FluctlightDB

Embedded memory database for AI agents — experience() / activate() / checkpoint(), Rust core, one brain directory per agent.

· GitHub · Paper DOI

Codex Community Hackathon: Fluctlight Swarm Memory — problem, architecture, and one-command demo

Fluctlight Swarm Memory — built with Codex

This hackathon prototype solves a failure mode in parallel coding agents: workers can receive duplicate context, repeat known failures, and promote unverified claims into shared knowledge. The Codex plugin gives every worker shared verified truth and warnings, but assigns different episodic strategies; it binds attempts to workers/worktrees and learns only from evidence accepted by a trusted verifier. State survives restarts through FluctlightDB WAL and v4 checkpoints.

Codex parallel agents were used to audit both codebases, design the transaction model, implement the Rust coordinator and MCP hooks, discover and fix an MCP 2.0 compatibility issue, and run the verification suite. Reproduce the shipped artifact with:

Watch the 54-second Remotion terminal demo · Remotion source · Read the demo narration

python3 scripts/demo_codex_swarm.py

Install

python3 -m venv .venv && source .venv/bin/activate
pip install "fluctlightdb[native]>=0.5.10"   # Linux / macOS / Windows (x64 + arm64); abi3 wheel for Python 3.9–3.13

Stability: docs/STABILITY.md · Production / embedded: docs/PRODUCTION.md · docs/EMBEDDED.md · Embeddings / offline: docs/EMBEDDINGS.md

API (30 seconds)

from fluctlightdb import connect_embedded

brain = connect_embedded("/tmp/my-agent-brain")
brain.turn_begin()
brain.wm_push("User prefers dark mode", context="settings", salience=0.8)
print(brain.recall("dark mode"))   # WM lexical recall (same turn, no embedder)
brain.turn_end(flush=True)         # durable commit for restart / graph recall
brain.checkpoint()

(connect_agent() is equivalent for experiments; prefer connect_embedded() in shipped agents.)

Operation	Method	When
Write memory	experience() / wm_push()	Tool result, user fact, observation
Recall from cue	activate() / recall()	Paraphrased question, task context
Trust ground truth	verified=True, provenance	Ledger/file beats chat
Persist	checkpoint()	Survive restart

Modes: connect_embedded() (production single-agent) · connect_agent() · connect_chorus() (bulk IR/LoCoMo) · connect_index() (vector-fast baseline) · connect_project() (multi-tool monorepo).

Integrations: INTEGRATIONS.md · MCP: pip install "fluctlightdb[mcp]"

Benchmarks (frozen July 2026)

Source: benchmarks/results/paper-2026-07-09.json

Benchmark	Metric	Result	Lane
LoCoMo (1,982 gold spans)	Honest evidence recall (no expansion)	96.8% @150 · 72.6% @5 (2627/2823 spans)	first-principles invented stack, native Rust engine (locomo_engine_maxsim.py)
LongMemEval-S	session_recall@8	97.6% (488/500)	hybrid index + mpnet (no Fabric)
LongMemEval E2E (locked)	Overall QA	97.4%	Muon + paper profile
BEIR SciFact	nDCG@10 / R@10	0.646 / 0.792 vs Chroma 0.645 / 0.783	CHORUS/PRISM + Fabric
FAMB	Macro	100%	agent + CHORUS (internal regression)

We report the honest raw number only. A gold dia_id counts solely when that exact turn is retrieved into the top-150 — no neighbor expansion. The historical 99.0% applied expand_session_neighbors(±3) after retrieval, crediting neighbours never retrieved; we no longer headline it (a trivial BM25 baseline also hits ~99% under that inflated protocol, so it distinguishes nothing). The honest 96.8% @150 comes from a first-principles invented retrieval stack running natively in the Rust engine: episodic context binding (Tulving), salience-gated token-population MaxSim (predictive coding), conjunctive surprisal (Weber–Fechner + binding), and evidence-integration fusion (Ernst–Banks). Read tight-k too: @5=72.6%, @10=80.0% — @150 retrieves ~18% of a conversation and is a lenient ceiling; a real RAG turn uses the top ~5–20, so tight-k is the operational number. Reproduce: PYTHONPATH=sdks/python python benchmarks/locomo_engine_maxsim.py. LoCoMo evidence recall ≠ Mem0/Zep LLM-judge E2E QA — different metrics (QA accuracy unmeasured here). See BENCHMARKS.md and #2.

Reproduce LoCoMo (one command)

git clone https://github.com/voxmastery/FluctlightDB.git && cd FluctlightDB
make reproduce-locomo          # honest raw recall@k (no expansion); checks locomo-lateinteraction-2026-07-13.json
# from source (pre-PyPI): REPRODUCE_FROM_SOURCE=1 make reproduce-locomo

Full protocol: docs/BENCHMARKS.md · benchmarks/README.md

Verification: Harnesses are open; headline numbers are maintainer self-reported until an independent group publishes a reproduction. See docs/REPRODUCIBILITY.md · MAINTAINER.md.

---

Why this exists

Postgres stores rows with a fixed schema. Chroma/Qdrant stores vectors and returns nearest neighbors. Mem0-style layers extract chat facts and search an index behind an API.

None of them give you a database engine whose native operations are memory operations:

Layer	Native question	Typical API
Relational	Which rows match?	SELECT
Vector	What's similar?	vector_search()
Memory SDK	What should we extract from chat?	app pipeline + index
FluctlightDB	What did the agent learn, and what should recall return for this cue?	experience() / activate()

Problem	What others make you build	What FluctlightDB gives you
Agent restarts and forgets	Session DB + vector sync + glue	experience() + checkpoint()
User asks differently than stored	Hope embeddings match	Cue activation — lexical + semantic + graph
Chat vs tool/file output	Custom ranking	Provenance — verified evidence outranks chat
Long-running store bloat	Cron compaction scripts	Consolidation / sleep in-engine

Vision & data model: Manifesto · LaTeX: papers/arxiv-v1/ · Figures: papers/figures/

---

What makes it different

1. experience() / activate() / checkpoint() — memory-native contract, not INSERT + ANN glue.
2. Hybrid recall — FTS5 + vectors + graph spread in one activate(cue).
3. Two production lanes — connect_embedded() for shipped agents; connect_chorus() + PRISM (RaBitQ + QJL + SPECTRUM + float rerank) for IR.

---

Recall Fabric (opt-in)

Foundational memory mechanisms behind FLUCTLIGHT_FABRIC=1. Paper-profile CHORUS benchmarks (LoCoMo, BEIR, FAMB) run with Fabric on; default agent paths may leave it off.

export FLUCTLIGHT_FABRIC=1

Details in table below (advanced / research-oriented):

Module	Mechanism	What it buys agents
photon	SimHash + LSH	Sub-linear candidate filter
lattice	Multi-scale grid coordinates	Coarse↔fine recall
phase_parse	Theta-gamma binding	Role/order structure
forgetting	Ebbinghaus + rehearsal	Adaptive retention
chronos	Temporal DAG	Before/after/causal queries
confidence	Provenance fusion	Trust-weighted recall

---

Living Brain viewer

fluctlight serve --addr 127.0.0.1:8792 --path /data/my-agent
# open http://127.0.0.1:8792/brain

WebGL connectome + recall probe over /api/v1/export-graph, /api/v1/activate, etc.

---

Multi-agent monorepos

pip install "fluctlightdb[native,mcp]"
fluctlight-project init

Cursor + Claude + Codex share .fluctlight/project/ brains, handoffs, MCP. See MULTI_AGENT.md.

---

Choose your path

One agent (start here)     → pip install "fluctlightdb[native]==0.5.10" ; connect_embedded()
Monorepo multi-tool        → fluctlight-project init ; connect_project()
HTTP server                → Docker ghcr.io/voxmastery/fluctlightdb
Engine development         → clone + cargo (CONTRIBUTING.md)

HTTP server (optional)

docker pull ghcr.io/voxmastery/fluctlightdb:latest
docker run -p 8792:8792 \
  -e FLUCTLIGHT_API_KEYS=default:your-secret:write \
  -v fluctlight-data:/data \
  ghcr.io/voxmastery/fluctlightdb:latest

---

Documentation

Doc	For
GETTING_STARTED.md	Paths, storage, FAQ
STABILITY.md	Stable vs experimental APIs
PRODUCTION.md	Pinning, deploy checklist, soak expectations
EMBEDDINGS.md	Offline vs benchmark embed deps
BENCHMARKS.md	Paper protocol + citations
REPRODUCIBILITY.md	Verification status + reproduce scripts
LEADERBOARD.md	Public results policy (no third-party agent-memory registry)
INTEGRATIONS.md	LangChain, LlamaIndex, OpenAI Agents
MULTI_AGENT.md	Hub + spoke, MCP, handoffs
Manifesto.md	Brain-native design (vision)
PUBLISHING.md	PyPI release (maintainers)
MAINTAINER.md	Bus factor, co-maintainer path
CHANGELOG.md	Version history
CONTRIBUTING.md	Rust/Python contributors

---

Contributing

Using Fluctlight in an agent? pip install fluctlightdb — no Rust required.

Changing the engine? CONTRIBUTING.md · SECURITY.md · MAINTAINER.md

License

MIT OR Apache-2.0 — see LICENSE, LICENSE-MIT, LICENSE-APACHE.