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

pip install flux-memory

Windows fallback if flux is not on PATH:

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

flux init --name my-memory

This prompts for:

• Operating mode (caller_extracts or flux_extracts)

Initialization also writes MCP client snippets under:

~/.flux/<name>/integrations/

Start services

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:

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:

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:

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

flux stop --name my-memory

Check status

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:

flux mcp-config --name my-memory

Codex example:

[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

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

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

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 with any configured local model

Development

git clone https://github.com/harsh5i/flux-memory
cd flux-memory
pip install -e ".[test]"
pytest tests/

License

MIT - see LICENSE