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

Agentic Memory MCP

agorokh/agentic-memory-mcp

Bridge MCP para LightRAG com suporte a workspaces e controle de acesso

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que conecta clientes MCP (Claude Code, Cursor, Claude Desktop) a backends LightRAG para consultas de conhecimento. Oferece leitura de grafos de conhecimento com suporte a múltiplos workspaces, controle de acesso por allowlist e registro de frota centralizado para ambientes multi-tenant.

Instalação

$npx convez-ai agorokh/agentic-memory-mcp

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
1
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 4 meses
Versão
v0.1.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Integrar agentes com sistemas de memória baseados em grafos de conhecimento
  • Consultar bases de dados estruturadas via RAG em ambientes Enterprise
  • Fornecer acesso controlado a múltiplos workspaces LightRAG de um único servidor

Veredito

Ferramenta especializada e bem-arquitetada para integração de memória agentica em escala Enterprise. Requer conhecimento técnico de MCP, LightRAG e DevOps, mas resolve um problema real de routing de múltiplos backends com controle granular de permissões.

README

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

agentic-memory-mcp

CI License Python MCP

A read-path MCP server that exposes LightRAG backends to MCP-compatible agents (Claude Code, Cursor, Claude Desktop, any MCP client). Workspace-aware, with per-host allowlists and a registry-driven multi-tenant model so one bridge process can serve many LightRAG instances.

Used by the Choosing memory for enterprise agents study as the live read path against the SDLC-history corpus.

┌─────────────────────┐      stdio MCP        ┌─────────────────────┐    HTTP /query     ┌─────────────────┐
│  MCP client         │──────────────────────▶│  agentic-memory-mcp │──────────────────▶│  LightRAG       │
│  (Claude Code etc.) │                       │  (this server)      │                   │  workspace A    │
└─────────────────────┘                       │                     │                   └─────────────────┘
                                              │  fleet_registry.toml│                   ┌─────────────────┐
                                              │  + allowlist        │──────────────────▶│  LightRAG       │
                                              │                     │                   │  workspace B    │
                                              └─────────────────────┘                   └─────────────────┘

What it does

  • Read-only. No writes to the LightRAG backend (ingest stays in your separate ingest pipeline). The bridge only calls POST /query and GET /health.
  • Workspace-aware. Each MCP tool call carries a workspace parameter; the bridge looks up the workspace's HTTP endpoint from a fleet registry TOML file.
  • Allowlist per host. AGENTIC_MEMORY_ALLOWED_WORKSPACES env var limits which workspaces this process can route to. Different host machines see different workspace subsets.
  • Audit trail. Every tool call is logged (prompt-redacted by default; AGENTIC_MEMORY_LOG_PROMPTS=1 to include).
  • Pooled HTTP. A single shared httpx.AsyncClient handles all workspaces (tunable via env; see below).

Tools exposed via MCP

ToolWhat it doesLightRAG endpoint
query_knowledge_graphQuery with mix, semantic, keyword, global, hybrid, local, or naive modes. Returns JSON with http_status, ok, and result.POST /query
verify_server_healthReachability check (workspace="*" probes all visible workspaces).GET /health / GET /
get_graph_metadataPer-workspace /health payload.GET /health
check_indexing_statusSame /health payload with operator-friendly labels.GET /health
list_workspacesRegistry metadata after allowlist filtering (query_supported flag per row).(registry-only)

query_knowledge_graph parameters

ParameterDefaultNotes
prompt(required)Forwarded to LightRAG; max 32 000 characters.
workspaceauto when one visibleRequired when multiple workspaces are visible.
search_modemixsemantic → LightRAG local; keyword → naive.
limit60Caps serialized MCP JSON (~limit × 400 chars), not LightRAG top_k.
context_only / prompt_onlyfalseMap to LightRAG only_need_context / chunk inclusion.

No set_active_workspace — every tool call passes workspace explicitly.

Quick start

# 1. Install
pip install -e .

# 2. Copy and edit the example registry (schema v2)
cp examples/fleet_registry.example.toml ./fleet_registry.toml
$EDITOR fleet_registry.toml

# Localhost/private IPs require:
export AGENTIC_MEMORY_ALLOW_PRIVATE_ENDPOINTS=1

export AGENTIC_MEMORY_REGISTRY_PATH=$PWD/fleet_registry.toml

# 3. (Optional) allowlist a subset for this host
export AGENTIC_MEMORY_ALLOWED_WORKSPACES=my_workspace_a,my_workspace_b

# 4. Run the MCP server (stdio)
agentic-memory-mcp
# or: python -m agentic_memory.server

Connect from Claude Code by adding to .mcp.json:

{
  "mcpServers": {
    "agentic-memory": {
      "command": "agentic-memory-mcp",
      "env": {
        "AGENTIC_MEMORY_REGISTRY_PATH": "/abs/path/to/fleet_registry.toml",
        "AGENTIC_MEMORY_ALLOW_PRIVATE_ENDPOINTS": "1"
      }
    }
  }
}

Environment variables

VariableRequiredMeaning
AGENTIC_MEMORY_REGISTRY_PATHyesPath to fleet_registry.toml (prefer absolute).
AGENTIC_MEMORY_ALLOWED_WORKSPACESnoComma-separated workspace IDs. Empty = all enabled rows.
AGENTIC_MEMORY_ALLOW_PRIVATE_ENDPOINTSno1 / true to allow loopback and RFC1918 endpoints in the registry.
AGENTIC_MEMORY_LOG_PROMPTSnoLog raw prompts in audit JSON (avoid in shared log stacks).
AGENTIC_MEMORY_LOG_LEVELnoPython log level (default INFO).
AGENTIC_MEMORY_HTTP_MAX_CONNECTIONSnoShared httpx pool size (default 64).
AGENTIC_MEMORY_HTTP_MAX_KEEPALIVEnoKeepalive connections (default 16).
AGENTIC_MEMORY_QUERY_READ_TIMEOUT_SnoRead timeout for upstream HTTP (default 120).
AGENTIC_MEMORY_MAX_PROBE_CONCURRENCYnoParallelism for startup / verify_server_health("*") (default 8).
AGENTIC_MEMORY_JSON_PRETTYnoPretty-print MCP tool JSON when set truthy.

Fleet registry schema (v2)

Supported reader versions: "1" and "2". Writers should emit schema_version = "2".

schema_version = "2"

[[vaults]]
id = "my_workspace_a"
endpoint = "http://localhost:8020"
backend = "lightrag"          # only lightrag is queryable today
enabled = true
allowed_modes = ["mix", "hybrid", "semantic"]   # optional; default = all modes
origin = "repo-product"       # optional
graph_namespace = "..."       # optional; for graphiti metadata only
  • backend = "graphiti" rows are listed in list_workspaces but cannot be queried until a Graphiti read path exists.
  • allowed_modes restricts search_mode per workspace when set; an empty list denies all modes.
  • Endpoints must not embed credentials. Metadata hosts (e.g. cloud metadata URLs) are blocked.

A separate upstream pipeline is expected to materialise this file from your fleet declaration.

Trust model

  • Read-only bridge — only POST /query and GET /health on configured endpoints.
  • Host allowlist — AGENTIC_MEMORY_ALLOWED_WORKSPACES limits visible workspaces per process.
  • Audit logging — structured JSON on stderr; prompts hashed unless AGENTIC_MEMORY_LOG_PROMPTS is set.

Operational security

  • No MCP or upstream HTTP authentication — isolate the bridge process and restrict who can edit fleet_registry.toml.
  • Registry endpoints are capability URLs — the bridge will fetch whatever URL is configured (SSRF risk). Use network egress controls in production; set AGENTIC_MEMORY_ALLOW_PRIVATE_ENDPOINTS only for local dev.
  • Tool responses may include internal URLs from list_workspaces / health tools.

See SECURITY.md for coordinated disclosure and hardening notes.

Why this exists

Most agentic-memory bridges either lock you to one backend per process, or expose write capabilities on the read path. This bridge is deliberately the opposite: one process serves many workspaces, workspace is a per-call parameter, and the write path stays out of the agent's reach.

Development

pip install -e ".[dev]"
pytest --cov=agentic_memory --cov-fail-under=73 -v
ruff check src tests

Companion projects

License

Apache-2.0. Patent grant included.

Ver o original no GitHub

Bom para

Relacionados