convez.ai
MCP ServerIntegração & APIsAvançado
harsh5i

Flux Memory

harsh5i/flux-memory

Memória persistente e inteligente para agentes IA com auto-organização

Ver no GitHub
InicialPluginScore · de 0 a 100

Sistema de memória para IA baseado em grafo auto-organizável que persiste conhecimento com aprendizado contínuo. Oferece MCP server, API REST e SDK Python, com consolidação automática de memórias, detecção de contradições e visualizações interativas do grafo de conhecimento.

Instalação

$npx convez-ai harsh5i/flux-memory

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
v0.6.2
Issues abertas
0
Contribuidores
4

Casos de uso

  • Construir agentes IA com memória contextual duradoura e aprendizado contínuo
  • Persistir e recuperar conhecimento com relevância dinâmica em sistemas multi-agentes
  • Monitorar saúde e contradições em bases de conhecimento em evolução

Veredito

Solução robusta e sofisticada para persistência de memória em IA, com arquitetura de produção (daemon, controle de concorrência, rate limiting) e visualizações ricas. Exige profundidade técnica para integração efetiva, mas oferece capacidades únicas de auto-organização e consolidação de conhecimento.

README

A tradução para o português deste README ainda está na fila.

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:

ToolDescription
flux_storeStore a memory grain
flux_retrieveRetrieve relevant memories
flux_feedbackRate a retrieved grain (learning signal)
flux_healthCurrent health and signal statistics
flux_list_grainsList grains by status (active/dormant/quarantined/archived)
flux_onboardGet 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:

ParameterDefaultDescription
OPERATING_MODEflux_extractsLLM extraction mode
MCP_HOST127.0.0.1Reserved for network MCP transports
MCP_PORT7464Reserved MCP port
REST_HOST127.0.0.1REST bind host
REST_PORT7465REST API port
DASHBOARD_HOST127.0.0.1Dashboard bind host
DASHBOARD_PORT7462Dashboard port
READ_WORKERS3Concurrent read workers
MAX_GRAINS_PER_CALL100Batch ingestion cap
MAX_GRAINS_PER_MINUTE500Per-caller rate limit
MAX_WRITE_QUEUE_DEPTH1000Write queue backpressure cap
FEEDBACK_ENFORCEMENT_ENABLEDtrueRequire callers to submit feedback before repeated retrieval
FEEDBACK_ENFORCEMENT_GRACE_SECONDS60Delay before missing feedback blocks the same caller
FEEDBACK_ENFORCEMENT_MAX_BLOCK_SECONDS86400Maximum time a stale missing-feedback item can block retrieval
LLM_MODELllama3.1:8bOllama 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

Ver o original no GitHub

Bom para

Relacionados