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

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

Start

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

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

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

Python Client

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

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

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

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