57 lines
2.0 KiB
Markdown
57 lines
2.0 KiB
Markdown
# Memory Gateway — deploy
|
||
|
||
Componente server di **pi-qmem**: FastAPI + Qdrant 1.19 + Ollama (BGE-M3).
|
||
Nessun LLM in scrittura: l'agente salva record deliberati e strutturati.
|
||
|
||
```
|
||
pi (estensione pi-qmem) ──HTTPS/VPN──▶ Memory Gateway (FastAPI:8082) ──▶ Qdrant 1.19 (6333)
|
||
│
|
||
└──▶ Ollama BGE-M3 (11434, nativo host)
|
||
```
|
||
|
||
## Deploy (Docker Compose)
|
||
|
||
```bash
|
||
# 1. Prepara l'ambiente (vedi qmem-gateway/docker-compose.yml come riferimento)
|
||
cp .env.example .env
|
||
chmod 600 .env
|
||
# genera le chiavi:
|
||
# QDRANT_ADMIN_API_KEY=$(openssl rand -hex 32)
|
||
# QDRANT_READ_ONLY_API_KEY=$(openssl rand -hex 32)
|
||
# API_KEYS=$(openssl rand -hex 32) # chiave condivisa per gli agenti
|
||
|
||
# 2. Avvia
|
||
docker compose up -d --build
|
||
|
||
# 3. Verifica
|
||
curl http://127.0.0.1:8082/v1/status
|
||
```
|
||
|
||
Requisiti: Docker + Compose v2, Ollama con modello `bge-m3` sul host
|
||
(`ollama pull bge-m3`), porta 8082 libera sull'interfaccia VPN.
|
||
|
||
## API
|
||
|
||
| Endpoint | Descrizione |
|
||
|---|---|
|
||
| `POST /v1/memories` | Crea record (text, kind, agent_id, scope, **project_id obbligatorio**, source, expires_at, supersedes_id, supersede_reason) |
|
||
| `POST /v1/memories:search` | Ricerca semantica (query, kind, project_id, scope, top_k, include_superseded, min_score) |
|
||
| `GET /v1/memories/{id}` | Recupera per UUID |
|
||
| `DELETE /v1/memories/{id}` | Elimina per UUID |
|
||
| `GET /v1/meta/overview` | Discovery: scope×kind, progetti, agenti, superseduti (cache 60s) |
|
||
| `GET /v1/status` | Health + statistiche |
|
||
|
||
Auth: header `X-API-Key` (chiave condivisa, accesso completo). Rate limit 120 req/min per chiave. Audit log in JSON lines (docker logs).
|
||
|
||
## Sicurezza
|
||
|
||
- Qdrant bindato su 127.0.0.1; gateway solo su interfaccia VPN
|
||
- Chiavi in `.env` (0600), mai committate
|
||
- JWT RBAC su Qdrant (admin + read-only)
|
||
- Backup: snapshot Qdrant + rotazione 7 giorni (cron: `0 3 * * * /opt/memory/backup.sh`)
|
||
|
||
## Dettagli operativi
|
||
|
||
Procedure complete (teardown, restore, nginx, troubleshooting): vedi
|
||
`docs/playbook.md` nel repo pi-qmem.
|