{"id":51413859,"url":"https://github.com/voxmastery/fluctlightdb","last_synced_at":"2026-07-04T17:02:05.278Z","repository":{"id":366141398,"uuid":"1274987408","full_name":"voxmastery/FluctlightDB","owner":"voxmastery","description":"Database engine for AI agents — write memory, recall by cue, trust sources over chat. Not SQL, vector DB, or mem0.","archived":false,"fork":false,"pushed_at":"2026-07-02T08:23:22.000Z","size":863,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-07-02T09:24:14.976Z","etag":null,"topics":["agent-memory","ai-agents","brain-native","database","docker","episodic-memory","llm","memory","pypi","python","rust"],"latest_commit_sha":null,"homepage":"https://github.com/voxmastery/FluctlightDB","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/voxmastery.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-20T05:40:07.000Z","updated_at":"2026-07-02T08:23:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/voxmastery/FluctlightDB","commit_stats":null,"previous_names":["voxmastery/fluctlightdb"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/voxmastery/FluctlightDB","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxmastery%2FFluctlightDB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxmastery%2FFluctlightDB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxmastery%2FFluctlightDB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxmastery%2FFluctlightDB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/voxmastery","download_url":"https://codeload.github.com/voxmastery/FluctlightDB/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxmastery%2FFluctlightDB/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35129190,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","ai-agents","brain-native","database","docker","episodic-memory","llm","memory","pypi","python","rust"],"created_at":"2026-07-04T17:02:04.449Z","updated_at":"2026-07-04T17:02:05.269Z","avatar_url":"https://github.com/voxmastery.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FluctlightDB\n\n**The memory engine for AI agents** — not a vector database with an agent SDK bolted on.\n\nYour agent gets a **persistent brain on disk**: it **writes experiences**, **recalls them from a cue**, and **ranks trusted sources** (tool results, files, API responses, verified records) above unverified chat. One install, one data folder per agent, survives restarts.\n\n[![PyPI](https://img.shields.io/pypi/v/fluctlightdb)](https://pypi.org/project/fluctlightdb/) · [GitHub](https://github.com/voxmastery/FluctlightDB)\n\n## Mission\n\n**Goal:** become the default **database for agent memory** — the way SQLite became the default embedded DB for apps.\n\nLong-term agent memory is a **third data model** (alongside relational facts and vector similarity), not a feature bolted onto someone else's store. FluctlightDB exists to:\n\n1. **Define that model** — episodes, cue-driven recall, graph activation, separation, provenance, consolidation — as **engine-level** semantics.\n2. **Ship an embedded database** — `experience()` / `activate()` / `checkpoint()`, one store per agent, Rust core, no required cloud.\n3. **Prove it publicly** — LoCoMo, BEIR, FAMB with frozen, reproducible numbers.\n4. **Stay in scope** — agent memory only; not Postgres, not generic doc search, not hosted Mem0-style SaaS.\n\n**Who it's for** — build with FluctlightDB when your agent needs to:\n\n- **Learn and retain over time** — accumulate what it picked up from chat, tools, files, APIs, and observations; not reset every session\n- **Remember across sessions** — restarts, days or weeks of work, not just the current context window\n- **Recall from a vague cue** — the user asks differently than how the fact was stored\n- **Prefer evidence over chat** — ground-truth memories (tool results, files, verified data) outrank casual conversation or model guesses at recall time\n- **Run embedded** — one durable brain on disk (or your VPS / your git), no required memory SaaS\n- **Share a repo brain across tools** — Cursor, Claude Code, Codex in one monorepo with handoffs (`fluctlight-project init`)\n\nTypical fits: coding agents (solo or multi-tool teams), ops/automation bots, research assistants, game NPCs, personal assistants with real continuity.\n\nManaged cloud hosting is **not required** — git sync, local/VPS embedded brains, or your own `fluctlight-serve` hub are supported today. Optional managed sync is roadmap.\n\n### What we mean by “learning”\n\n**Not model training.** We do not update LLM weights. **Learning** here means **operational memory**:\n\n1. **Write** — the agent encodes episodes with context and salience (`experience()`).\n2. **Link \u0026 rank** — related memories connect; trusted sources outrank chat (graph activation, provenance).\n3. **Consolidate** — sleep/compaction prunes noise over time (`sleep()`, `checkpoint()`).\n4. **Recall** — a new cue activates what mattered before (`activate()`), even under paraphrase.\n\nThe store gets richer and more useful the longer the agent runs. Chat logs and raw vectors alone do not provide that lifecycle — a **memory engine** does. Deeper framing: [Manifesto](docs/Manifesto.md) (*“learning is plasticity”* — Hebbian links, consolidation, growth).\n\nDeep design: [Manifesto](docs/Manifesto.md) · **Paper DOI:** [10.5281/zenodo.20949890](https://doi.org/10.5281/zenodo.20949890) · LaTeX: [`papers/arxiv-v1/`](papers/arxiv-v1/) · **Figures:** [`papers/figures/`](papers/figures/)\n\n```bash\npip install \"fluctlightdb[native]\"\n```\n\n```python\nfrom fluctlightdb import connect\n\nbrain = connect(\"/tmp/my-agent-brain\")\nbrain.experience(\"User prefers dark mode\", context=\"settings\", salience=0.8)\nprint(brain.activate(\"theme preference\"))\nbrain.checkpoint()\n```\n\n---\n\n## Why this exists\n\n**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.\n\nNone of them give you a **database engine whose native operations are memory operations**:\n\n| Layer | Native question | Typical API |\n|-------|-----------------|-----------|\n| Relational | Which rows match? | `SELECT` |\n| Vector | What's similar? | `vector_search()` |\n| Memory SDK | What should we extract from chat? | app pipeline + index |\n| **FluctlightDB** | What did the agent learn, and what should recall return for this cue? | `experience()` / `activate()` |\n\nThat gap shows up as the same pain in every serious agent:\n\n| Problem | What others make you build | What FluctlightDB gives you |\n|---------|---------------------------|----------------------------|\n| Agent restarts and forgets | Session DB + vector sync + glue code | `experience()` + `checkpoint()` — one folder per agent |\n| User asks differently than you stored | Hope embeddings match | **Cue activation** — lexical + semantic + graph links (paraphrase recall) |\n| Related memories should surface together | Manual chunking / reranking | **Spreading activation** over linked engrams |\n| Noisy or repeated writes | Your dedup logic | **Separation gate** at write time |\n| Chat vs tool/file/API output | Custom ranking in app code | **Provenance** — verified evidence outranks unverified chat |\n| Long-running store gets bloated | Cron jobs and one-off scripts | **Consolidation / sleep** in the engine |\n| “Just bulk-index docs for a benchmark” | A separate vector DB | `connect_index()` — same engine, IR mode |\n\n**In one line:** FluctlightDB is a **database engine for what agents learn** — write episodes, recall from cues, hybrid retrieval, evidence ranking, compaction — **embedded on disk**, not a hosted memory SaaS and not a replacement for Postgres.\n\n**Proof:** **98.1%** LoCoMo evidence recall · **98.0%** LongMemEval-S session@8 · BEIR SciFact parity · FAMB **97–98%** — [frozen results](benchmarks/results/paper-2026-07-04.json).\n\n---\n\n## What makes it different\n\nThe items above are **engine primitives**, not plugins you wire up yourself:\n\n1. **`experience()` / `activate()` / `checkpoint()`** — the database contract (not `INSERT` + `vector_search()` + custom glue).\n2. **Hybrid recall** — vectors, keywords, and graph activation in one `activate(cue)` call.\n3. **Two modes** — `connect()` for live agents; `connect_index()` for bulk ingest and IR benchmarks.\n\nDetails: [Manifesto](docs/Manifesto.md) · optional brain-native internals · use it like SQLite for agents without reading neuroscience.\n\n---\n\n## Where it is going\n\n- **Now:** embedded Python/Rust, HTTP server, provenance-aware recall, **98.1% LoCoMo** + **98.0% LongMemEval-S** (composite retrieval runs), BEIR SciFact parity, FAMB 97–98%, **multi-agent project brains** (MCP + hooks + handoffs, Windows/macOS/Linux).\n- **Next:** full 500 v4 confirmation run, LoCoMo end-to-end QA vs Mem0/Zep on defined metrics, multi-tenant scale at 100k+ memories, optional managed sync (self-hosted works today).\n- **Goal:** the default **database engine for agent memory** — the way SQLite became the default embedded DB for apps.\n- **Long-term vision:** **foundational memory infrastructure** for durable, trustworthy autonomy — the persistence layer between a stateless LLM call and agents (or stacks) that must operate over weeks, prefer evidence over chat, and carry identity across tools. We are building the **database for that layer**, not claiming to be AGI. Any serious path toward general, long-horizon autonomy still needs a third data model for *what was learned and what can be trusted*; FluctlightDB is that engine.\n\n---\n\n## Benchmarks\n\nFrozen results: [`benchmarks/results/paper-2026-07-04.json`](benchmarks/results/paper-2026-07-04.json)\n\n### Latest measured results (July 2026)\n\n| Benchmark | Metric | FluctlightDB | Baseline / note |\n|-----------|--------|--------------|-----------------|\n| **LoCoMo** (10 conv, 1,982 gold spans) | Mean **evidence recall** @ k=150 | **98.1%** (1925/1982) | Warm and cold-start identical |\n| | All evidence in context | 97.1% | Hybrid vector + BM25, index mode |\n| | Wall time | 271s warm / 335s cold | 2 CPU threads, MiniLM ONNX |\n| **LongMemEval-S** (500 Q) | **session_recall@8** | **98.0%** (490/500) | mpnet GPU v4 composite |\n| | By type (preference) | **96.7%** (29/30) | v4 pref-facts-key |\n| | Wall time | 3203s (~6.4 s/Q) | Colab GPU; see `longmemeval_colab.ipynb` |\n| **BEIR SciFact** | nDCG@10 (index mode) | **0.645** | Chroma + same MiniLM: 0.645 (tie) |\n| | Recall@100 (agent mode) | **0.941** | Chroma: 0.925 |\n| | Query latency (index) | **4–7 ms** | Chroma: 4–7 ms |\n| **FAMB** (agent-specific) | Macro (index mode) | **98%** | Paraphrase 92%, provenance/persistence 100% |\n| | Macro (agent mode) | **97%** | Paraphrase 83%, other suites 100% |\n\n\u003e **Metric note:** LoCoMo **evidence recall** and LongMemEval **session_recall@K** are retrieval metrics (gold evidence/session in top-K). Mem0/Zep often report **LLM-as-judge end-to-end QA** — a harder, different number. Do not compare retrieval % to QA % without naming the metric.\n\n### Reproduce\n\nClone the repo, install deps, run from repo root:\n\n```bash\npython3 -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install chromadb pytrec-eval-terrier \"fluctlightdb[native]\"\n# or dev: pip install -e sdks/python \u0026\u0026 ./scripts/install-native.sh\n\n# Agent memory (paraphrase, provenance, persistence) — ~4 min\nPYTHONPATH=sdks/python python benchmarks/agent_memory_bench.py --mode agent\nPYTHONPATH=sdks/python python benchmarks/agent_memory_bench.py --mode index\n\n# BEIR SciFact (download once)\nmkdir -p /tmp/beir \u0026\u0026 cd /tmp/beir\ncurl -sL https://public.ukp.informatik.tu-darmstadt.de/thakur/BEIR/datasets/scifact.zip -o scifact.zip\nunzip -o scifact.zip \u0026\u0026 cd -\n\nBEIR_DATA=/tmp/beir BEIR_DS=scifact MODE=index PYTHONPATH=sdks/python python benchmarks/beir_bench.py\n\n# LoCoMo full eval (needs dataset — see benchmarks/README.md)\nPYTHONPATH=sdks/python python benchmarks/locomo_eval.py --mode index --rag-mode all --top-k 150\n\n# LongMemEval (pilot / full — CPU-heavy ingest)\nPYTHONPATH=sdks/python python benchmarks/longmemeval_bench.py --mode index\n```\n\nFull citations and paper protocol: **[docs/BENCHMARKS.md](docs/BENCHMARKS.md)** · **[benchmarks/README.md](benchmarks/README.md)** · **[Paper (LaTeX)](papers/arxiv-v1/)** · **DOI [10.5281/zenodo.20949890](https://doi.org/10.5281/zenodo.20949890)**\n\n## Quick start\n\nOn Debian/Ubuntu/Fedora, use a venv ([PEP 668](https://peps.python.org/pep-0668/)):\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install \"fluctlightdb[native]\"\n```\n\n```python\nfrom fluctlightdb import connect, connect_index\n\n# Live agent — full memory path (provenance, separation, graph)\nbrain = connect(\"/data/my-agent\")\n\n# Bulk semantic index — RAG backfill or IR benchmarks\nindex = connect_index(\"/data/rag-index\")\n```\n\n| You need to… | API | Example |\n|--------------|-----|---------|\n| Save a memory | `experience(...)` | User preference, tool result, observation |\n| Recall from a hint | `activate(cue)` | “What do we know about billing?” |\n| Mark ground truth | `verified=True`, provenance | Ledger/file-backed facts |\n| Persist to disk | `checkpoint()` | Survive process restart |\n\n---\n\n## Multi-agent monorepos (Cursor + Claude + Codex)\n\n**One repo, many AI tools, one shared project brain.** FluctlightDB v0.5+ scaffolds hub-and-spoke memory for monorepos where Cursor, Claude Code, and Codex work on the same codebase:\n\n```\n.fluctlight/\n  project/          ← shared decisions, conventions, handoffs\n  agents/cursor|claude|codex/   ← per-tool session notes\n  handoffs.jsonl    ← deterministic handoff inbox\n```\n\n```bash\npip install \"fluctlightdb[native,mcp]\"\nfluctlight-project init\nfluctlight-project doctor\n```\n\n```python\nfrom fluctlightdb import connect_project\n\npb = connect_project()  # auto-detects Cursor / Claude / Codex\npb.handoff(\"Paused auth work\", next_steps=[\"Add tests\"], files=[\"src/auth.py\"])\nprint(pb.list_handoffs())\n```\n\n**Includes:** MCP tools, Cursor hooks + **required rules**, Claude skill + MCP, Codex MCP, **handoff web UI**, **git sync**, optional **VPS hub**. **Windows, macOS, Linux.**\n\n```bash\nfluctlight-project ui       # inbox at http://127.0.0.1:8787\nfluctlight-project sync pull  # VPS ↔ laptop via git\nfluctlight-project onboard    # guided setup\n```\n\n**VPS Cursor CLI + local desktop?** Yes — [VPS_DESKTOP.md](docs/VPS_DESKTOP.md)\n\nFull guide: **[MULTI_AGENT.md](docs/MULTI_AGENT.md)** · onboarding: **[ONBOARDING.md](docs/ONBOARDING.md)** · compatibility: **[PLATFORM_COMPAT.md](docs/PLATFORM_COMPAT.md)**\n\n---\n\n## Choose your path\n\n```\nOne agent in one process (start here)\n  pip install \"fluctlightdb[native]\"\n  brain = connect(\"/path/to/agent-data\")\n\nSeveral agents / one monorepo (Cursor, Claude, Codex)\n  pip install \"fluctlightdb[native,mcp]\"\n  fluctlight-project init  →  connect_project()\n\nSeveral agents / shared HTTP server\n  pip install fluctlightdb\n  Docker → FluctlightClient over HTTP\n\nTerminal exploration\n  fluctlight shell  (GitHub Releases binary)\n\nEngine / CLI development\n  clone + cargo — CONTRIBUTING.md\n```\n\n### HTTP server (optional)\n\n```bash\ndocker pull ghcr.io/voxmastery/fluctlightdb:latest\ndocker run -p 8792:8792 \\\n  -e FLUCTLIGHT_API_KEYS=default:your-secret:write \\\n  -v fluctlight-data:/data \\\n  ghcr.io/voxmastery/fluctlightdb:latest\n```\n\nProduction: [DEPLOYMENT.md](docs/DEPLOYMENT.md) · [DOCKER.md](docs/DOCKER.md)\n\n---\n\n## Documentation\n\n| Doc | For |\n|-----|-----|\n| **[Getting started](docs/GETTING_STARTED.md)** | Paths, storage, FAQ |\n| **[BENCHMARKS.md](docs/BENCHMARKS.md)** | Paper-ready eval + citations |\n| **[MULTI_AGENT.md](docs/MULTI_AGENT.md)** | Hub + spoke brains, MCP, hooks, handoffs |\n| **[ONBOARDING.md](docs/ONBOARDING.md)** | 5-minute setup · `fluctlight-project onboard` |\n| **[VPS_DESKTOP.md](docs/VPS_DESKTOP.md)** | Cursor CLI on VPS + local desktop |\n| **[PLATFORM_COMPAT.md](docs/PLATFORM_COMPAT.md)** | Windows / macOS / Linux matrix |\n| [PUBLISHING.md](docs/PUBLISHING.md) | PyPI release (maintainers) |\n| [CLI.md](docs/CLI.md) | `fluctlight shell` |\n| [Manifesto.md](docs/Manifesto.md) | Brain-native design |\n| [CONTRIBUTING.md](CONTRIBUTING.md) | Rust/Python contributors |\n\n---\n\n## Contributing\n\n**Using Fluctlight in an agent?** `pip install fluctlightdb` — no Rust required.\n\n**Changing the engine?** [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md)\n\n## License\n\nMIT OR Apache-2.0 — see `LICENSE`, `LICENSE-MIT`, `LICENSE-APACHE`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoxmastery%2Ffluctlightdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoxmastery%2Ffluctlightdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoxmastery%2Ffluctlightdb/lists"}