Content
# Flux Memory
**Self-organizing retrieval fabric for AI memory.**
Flux Memory is an AI memory system that persists knowledge as a self-modifying weighted graph. It learns which memories matter through feedback signals - reinforcing useful grains, decaying stale ones, and automatically clustering related knowledge.
## Features
- **Graph-based memory** - grains connected by weighted, typed conduits, propagated via signal attenuation
- **Self-organizing** - lazy decay, Louvain clustering, automatic promotion/demotion, shortcut reinforcement
- **Epistemic layer** - contradiction & supersession detection, per-grain confidence that evolves with corroboration and age, typed relations (`contradicts` / `supersedes` / `supports` / `caused_by`), and tombstones that survive forgetting
- **Memory consolidation ("dream cycle")** - the daemon periodically abstracts dense clumps of related grains into one higher-level grain, gated against hallucination
- **Health monitor** - 14 first-class signals, snapshot history, optional Telegram alerts on new warnings
- **Live visualizations** - five dashboard views: Knowledge Graph, Mycelium, Globe, Vitals (signal timelines), and Chronicle (semantic replay with real-time activity, search beam, cluster hulls, heat trails, grain dossier)
- **Three access paths** - MCP server (for AI agents), REST API (HTTP), Python SDK
- **Single-writer daemon** - MCP processes run as thin clients of the running service; only the daemon opens the database
- **Booth architecture** - concurrent read workers, serial write queue, async feedback queue
- **Per-caller rate limiting & feedback enforcement** - 500 grains/min default; callers close retrieval feedback loops
- **Two operating modes** - `flux_extracts` (LLM extracts grains) or `caller_extracts` (AI provides content directly)
## Quick Start
### Install
```bash
pip install flux-memory
```
Windows fallback if `flux` is not on PATH:
```bat
python -m flux --help
python -m flux init --name my-memory
```
For CLI-first installs, `pipx install flux-memory` is recommended because it manages command shims and PATH setup.
### Initialize an instance
```bash
flux init --name my-memory
```
This prompts for:
- Operating mode (`caller_extracts` or `flux_extracts`)
Initialization also writes MCP client snippets under:
```text
~/.flux/<name>/integrations/
```
### Start services
```bash
flux start --name my-memory
```
Starts:
- REST API health endpoint at `http://localhost:7465/health`
- Dashboard at `http://localhost:7462` — views: `/` (Knowledge Graph), `/mycelium`, `/globe`, `/chronicle` (semantic replay), `/vitals` (health timelines)
To view the dashboard from a phone on the same local network, start with:
```bash
flux start --name my-memory --broadcast
```
This binds the dashboard to `0.0.0.0`, prints LAN URLs such as
`http://192.168.x.x:7462`, and serves a device-frame preview at
`/mobile-preview`. The REST API remains local-only by default.
For private access from outside the local network, use a tailnet/VPN such as
Tailscale instead of router port forwarding. Keep Flux running locally, sign in
to Tailscale on this machine and the remote device, then publish only the
dashboard to your private tailnet:
```bash
flux start --name my-memory
tailscale serve --http=7462 http://127.0.0.1:7462
tailscale serve status
```
Then open `http://<tailscale-device-name>:7462` from another signed-in
Tailscale device. This keeps the dashboard private to your tailnet and does not
expose the REST API or MCP transport to the public internet.
If you do not want an overlay app, the private alternative is your own VPN
endpoint, usually on your router/firewall. Connect to that VPN from the office
using an OS-supported VPN profile, then open the dashboard over the home LAN
address printed by `flux start --name my-memory --broadcast`. Do not forward
port `7462` directly from the router to the internet.
`flux start` does not make the stdio MCP server discoverable by itself. MCP clients launch stdio servers directly. Use the generated snippet or run:
```bash
flux mcp --name my-memory
```
from your MCP client configuration.
In other words, `flux start` starts only the REST API and dashboard. It does
not start a background network MCP server that Codex, Claude, Cursor, or other
clients can auto-detect. Each MCP client must have its own config entry.
### Stop services
```bash
flux stop --name my-memory
```
### Check status
```bash
flux status --name my-memory
```
## MCP Integration
Connect Flux Memory to any MCP-compatible AI agent. Flux uses stdio MCP by default, so the client must launch Flux.
Generate or refresh client snippets:
```bash
flux mcp-config --name my-memory
```
Codex example:
```toml
[mcp_servers."flux-my-memory"]
command = "python"
args = ["-m", "flux.cli", "mcp", "--name", "my-memory"]
```
On first connection, call `flux_onboard` to receive integration instructions:
```
flux_onboard() -> returns workflow instructions + operating mode
```
**Standard workflow per conversation turn:**
1. `flux_retrieve(query)` - fetch relevant memories before responding
2. `flux_store(content, provenance)` - save new facts after responding
3. `flux_feedback(trace_id, grain_id, useful)` - rate each retrieved grain
Every client should also send a portable caller identity:
- `client`: any stable AI/tool name, such as `codex`, `claude`, or `local-agent-1`
- `role`: one of `chat`, `memory_writer`, `background_lookup`, `system`, `admin`, `test`
Use `caller_id="<client>:<role>"`, for example `local-agent-1:chat`.
MCP clients may instead send separate `client` and `role` fields.
For clients such as Codex, save the `flux_onboard` instructions into an
always-loaded instruction surface, such as a project or user `AGENTS.md`.
Saving the workflow only as a memory note is not enough, because the agent must
already remember to use Flux before it can retrieve that note.
**Available MCP tools:**
| Tool | Description |
|------|-------------|
| `flux_store` | Store a memory grain |
| `flux_retrieve` | Retrieve relevant memories |
| `flux_feedback` | Rate a retrieved grain (learning signal) |
| `flux_health` | Current health and signal statistics |
| `flux_list_grains` | List grains by status (active/dormant/quarantined/archived) |
| `flux_onboard` | Get integration instructions for this instance |
## REST API
```http
POST /store {"content": "...", "provenance": "user_stated"}
POST /store/batch {"items": [{"content": "..."}]}
POST /retrieve {"query": "..."}
POST /feedback {"trace_id": "...", "grain_id": "...", "useful": true}
GET /health
GET /grains?status=active&limit=50
```
Pass `X-Flux-Client` and `X-Flux-Role` headers for caller attribution, or use
legacy `X-Caller-Id: <client>:<role>`. Dashboard compliance groups calls by
client and role.
## Python SDK
```python
from flux.storage import FluxStore
from flux.service import FluxService
from flux.config import Config
store = FluxStore("~/.flux/my-memory/flux.db")
svc = FluxService(store, cfg=Config())
svc.start()
grain_id = svc.store("Paris is the capital of France", provenance="user_stated")
result = svc.retrieve("French capital")
svc.feedback(result.trace_id, result.grains[0]["id"], useful=True)
svc.stop()
store.close()
```
## Configuration
Instance config lives at `~/.flux/<name>/config.yaml`. Key parameters:
| Parameter | Default | Description |
|-----------|---------|-------------|
| `OPERATING_MODE` | `flux_extracts` | LLM extraction mode |
| `MCP_HOST` | `127.0.0.1` | Reserved for network MCP transports |
| `MCP_PORT` | `7464` | Reserved MCP port |
| `REST_HOST` | `127.0.0.1` | REST bind host |
| `REST_PORT` | `7465` | REST API port |
| `DASHBOARD_HOST` | `127.0.0.1` | Dashboard bind host |
| `DASHBOARD_PORT` | `7462` | Dashboard port |
| `READ_WORKERS` | `3` | Concurrent read workers |
| `MAX_GRAINS_PER_CALL` | `100` | Batch ingestion cap |
| `MAX_GRAINS_PER_MINUTE` | `500` | Per-caller rate limit |
| `MAX_WRITE_QUEUE_DEPTH` | `1000` | Write queue backpressure cap |
| `FEEDBACK_ENFORCEMENT_ENABLED` | `true` | Require callers to submit feedback before repeated retrieval |
| `FEEDBACK_ENFORCEMENT_GRACE_SECONDS` | `60` | Delay before missing feedback blocks the same caller |
| `FEEDBACK_ENFORCEMENT_MAX_BLOCK_SECONDS` | `86400` | Maximum time a stale missing-feedback item can block retrieval |
| `LLM_MODEL` | `llama3.1:8b` | Ollama model (flux_extracts mode) |
## Admin
```bash
flux admin --name my-memory
```
Interactive menu: search/purge/restore grains, view audit log, export grain details, open dashboard. Destructive operations (purge) require a session-local confirmation token, generated automatically, which prevents accidental programmatic deletion — there is no password to set or forget.
## Requirements
- Python 3.10+
- SQLite 3.35+ (WAL mode)
- For `flux_extracts` mode: [Ollama](https://ollama.ai) with any configured local model
## Development
```bash
git clone https://github.com/harsh5i/flux-memory
cd flux-memory
pip install -e ".[test]"
pytest tests/
```
## License
MIT - see [LICENSE](LICENSE)
