Metadata-Version: 2.4
Name: fluctlightdb
Version: 0.5.8
Summary: Embedded memory engine for AI agents — third data model (experience/activate), provenance, benchmarks. Goal: SQLite for agent memory.
Author-email: Ganesh S <voxmastery@ambugo.tech>
License-Expression: MIT OR Apache-2.0
Project-URL: Homepage, https://github.com/voxmastery/FluctlightDB
Project-URL: Documentation, https://github.com/voxmastery/FluctlightDB/blob/main/docs/GETTING_STARTED.md
Project-URL: Repository, https://github.com/voxmastery/FluctlightDB
Project-URL: Issues, https://github.com/voxmastery/FluctlightDB/issues
Project-URL: Paper, https://github.com/voxmastery/FluctlightDB/tree/main/papers/arxiv-v1
Project-URL: Benchmarks, https://github.com/voxmastery/FluctlightDB/blob/main/benchmarks/results/paper-2026-07-09.json
Keywords: ai-agents,agent-memory,database,embedded-database,llm,memory,rag,recall,rust
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-APACHE
Requires-Dist: PyYAML>=6.0
Requires-Dist: filelock>=3.13
Provides-Extra: native
Requires-Dist: fluctlightdb-native>=0.5.8; extra == "native"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2.0; extra == "langchain"
Requires-Dist: fluctlightdb[native]; extra == "langchain"
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.10.0; extra == "llamaindex"
Requires-Dist: fluctlightdb[native]; extra == "llamaindex"
Provides-Extra: agents
Requires-Dist: fluctlightdb[native]; extra == "agents"
Provides-Extra: all
Requires-Dist: fluctlightdb[langchain,llamaindex,mcp,native]; extra == "all"
Dynamic: license-file

# FluctlightDB

**The memory engine for AI agents** — not a vector database with an agent SDK bolted on.

[![PyPI](https://pypi.org/project/fluctlightdb/)](https://pypi.org/project/fluctlightdb/) · [GitHub](https://github.com/voxmastery/FluctlightDB)

## Mission

**Goal:** become the default **database for agent memory** — the way SQLite became the default embedded DB for apps.

Long-term agent memory is a **third data model** (alongside relational facts and vector similarity). FluctlightDB defines engine-level `experience()` / `activate()` semantics — episodes, cue-driven recall, provenance, consolidation — not app glue on top of Chroma or Mem0.

**Who it's for** — agents that **learn and retain** across sessions (from chat, tools, files, and APIs), recall under paraphrase, prefer **verified evidence** over casual conversation at recall time, and — in monorepos — **share a project brain** across Cursor, Claude Code, and Codex (`fluctlight-project init`). No hosted SaaS required.

**What “learning” means** — not fine-tuning. The agent **writes** episodes (`experience()`), **recalls** under new cues (`activate()`), and **consolidates** over time (`sleep()` / `checkpoint()`). See the [full README](https://github.com/voxmastery/FluctlightDB#what-we-mean-by-learning) and [Manifesto](https://github.com/voxmastery/FluctlightDB/blob/main/docs/Manifesto.md).

Typical fits: coding agents, ops bots, research assistants, NPCs.

## Install

```bash
pip install "fluctlightdb[native]"
```

```python
from fluctlightdb import connect

brain = connect("/tmp/my-agent-brain")
brain.experience("User prefers dark mode", context="settings", salience=0.8)
print(brain.activate("dark mode"))  # offline lexical cue (paraphrase needs semantic_vector)
brain.checkpoint()
```

HTTP-only (no Rust extension): `pip install fluctlightdb`

## Benchmarks (June 2026)

| Benchmark | Metric | Result |
|-----------|--------|--------|
| **LoCoMo** (10 conv) | Mean evidence recall @ k=150 | **99.0%** |
| **BEIR SciFact** | nDCG@10 (index mode) | **0.645** (ties Chroma + MiniLM) |
| **FAMB** | Macro (index / agent) | **98%** / **97%** |

Frozen JSON: [benchmarks/results/paper-2026-07-09.json](https://github.com/voxmastery/FluctlightDB/blob/main/benchmarks/results/paper-2026-07-09.json)

> LoCoMo **evidence recall** ≠ Mem0 **LLM-as-judge QA** — different metrics; compare only when labeled.

## Docs

- [Getting started](https://github.com/voxmastery/FluctlightDB/blob/main/docs/GETTING_STARTED.md)
- [Multi-agent monorepos](https://github.com/voxmastery/FluctlightDB/blob/main/docs/MULTI_AGENT.md) — `fluctlight-project init`, MCP, hooks, handoffs
- [Platform compatibility](https://github.com/voxmastery/FluctlightDB/blob/main/docs/PLATFORM_COMPAT.md) — Windows, macOS, Linux
- [Full README & reproduction](https://github.com/voxmastery/FluctlightDB)
- [Paper (LaTeX)](https://github.com/voxmastery/FluctlightDB/tree/main/papers/arxiv-v1)
