Metadata-Version: 2.4
Name: fluctlightdb
Version: 0.5.0
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
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/2025-06-22.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
Requires-Dist: PyYAML>=6.0
Requires-Dist: filelock>=3.13
Provides-Extra: native
Requires-Dist: fluctlightdb-native>=0.4.3; extra == "native"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
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 persist across sessions, learn from tools/files/APIs as well as chat, recall under paraphrase, and should prefer **verified evidence** over casual conversation at recall time.

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("theme preference"))
brain.checkpoint()
```

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

## Benchmarks (June 2025)

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

Frozen JSON: [benchmarks/results/2025-06-22.json](https://github.com/voxmastery/FluctlightDB/blob/main/benchmarks/results/2025-06-22.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)
- [Platform checklist](https://github.com/voxmastery/FluctlightDB/blob/main/docs/PLATFORMS.md)
