agentMemo — Semantic Memory Mesh#

FastAPI-based memory server with HNSW embeddings, hybrid search, versioning, RBAC, and real-time event bus for AI agents.

Prerequisites#

• Python 3.12+ and pip
• AGENTMEMO_ADMIN_KEY environment variable (required, secret) — the server refuses to start without it
• Network access on first run: the embedding model (all-MiniLM-L6-v2, ~90MB) is downloaded from HuggingFace on first startup and cached locally at ~/.cache/torch/sentence_transformers/

Install#

bash

pip install -r requirements.txt

This installs FastAPI, uvicorn, sentence-transformers, hnswlib, aiosqlite, and other dependencies. Review requirements.txt before running. Prefer installing inside a virtualenv or container.

Required Environment Variables#

VariableRequiredSecretDefaultDescriptionAGENTMEMO_ADMIN_KEYyes****yes—API key for RBAC auth. Server exits if unset.AGENTMEMO_PORTnono8790HTTP port (localhost only)AGENTMEMO_DBnonoagentmemo.dbSQLite DB pathAGENTMEMO_RATE_LIMITnono120Requests/min per keyAGENTMEMO_POOL_SIZEnono5DB connection pool size

Start#

bash

export AGENTMEMO_ADMIN_KEY="your-secret-key"
python server.py

The server binds to 127.0.0.1:8790 (localhost only). For networked deployments, use a reverse proxy with TLS + auth. Never expose port 8790 to the internet directly.

Security#

• Auth is mandatory: server refuses to start without AGENTMEMO_ADMIN_KEY
• All endpoints require X-API-Key header (except /health)
• Localhost binding by default: only accessible from the local machine
• First-run network activity: downloads embedding model (~90MB) from HuggingFace; subsequent starts use local cache

Quick Reference#

Store#

bash

curl -X POST http://localhost:8790/v1/memories \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your-secret-key' \
  -d '{"text": "User prefers dark mode", "namespace": "prefs", "tags": ["ui"], "importance": 0.9}'

Search#

bash

curl -H 'X-API-Key: your-secret-key' \
  'http://localhost:8790/v1/memories/search?q=dark+mode&mode=hybrid&tags=ui'

Python Client#

python

from client import AgentMemoClient
memo = AgentMemoClient("http://localhost:8790", api_key="your-secret-key")
memo.store("Decision: use PostgreSQL", namespace="arch", tags=["db"], importance=0.8)
results = memo.search("database choice", mode="hybrid")

Batch API#

bash

curl -X POST http://localhost:8790/v1/memories/batch \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your-secret-key' \
  -d '{"operations": [{"op": "create", "text": "fact A"}, {"op": "create", "text": "fact B"}]}'

Versioning & Rollback#

bash

curl -H 'X-API-Key: your-secret-key' http://localhost:8790/v1/memories/{id}/versions
curl -X POST -H 'X-API-Key: your-secret-key' \
  http://localhost:8790/v1/memories/{id}/rollback -d '{"version": 2}'

API Endpoints#

MethodPathDescriptionGET/healthHealth check (no auth)GET/metricsServer metricsGET/dashboardWeb dashboardPOST/v1/memoriesStore memoryGET/v1/memories/searchSearch (semantic/keyword/hybrid)PUT/v1/memories/{id}Update (creates new version)DELETE/v1/memories/{id}DeleteGET/v1/memories/{id}/versionsVersion historyPOST/v1/memories/{id}/rollbackRollback to versionPOST/v1/memories/batchBatch operationsPOST/v1/importBulk importGET/v1/exportBulk exportGET/v1/events/streamSSE event streamWS/v1/wsWebSocket stream

Key Features#

• Hybrid Search: RRF fusion of semantic (HNSW cosine) + keyword (BM25-style)
• Importance Decay: score = importance × 0.5^(age/half_life) — older memories fade naturally
• Versioning: Every update creates a new version; full rollback support
• RBAC: Namespace isolation + API key access control
• Event Bus: SSE + WebSocket for real-time agent-to-agent notifications
• Dashboard: Web UI at /dashboard for browsing and searching memories