agentMemo

agentMemo is a Semantic Memory Mesh server for AI agents. Use this skill when you need to store, search, or retrieve agent memory across sessions with semant...

Security Scan

The package appears to implement a local semantic-memory server (matches its description) but the registry metadata and SKILL.md disagree about required environment and install steps, and code/installer files are included without an automated install spec — review before running.

Purpose & Capability

Name/description (semantic memory mesh) align with included source files (server.py, client.py, database.py, embeddings.py, etc.). The code and documentation implement the FastAPI + SQLite + HNSW memory server described.

Instruction Scope

SKILL.md gives concrete startup/install instructions (pip install -r requirements.txt, set AGENTMEMO_ADMIN_KEY, python server.py), binds to localhost, and documents endpoints. The runtime instructions do not direct the agent to read unrelated system files or external endpoints beyond downloading the embedding model from HuggingFace. However SKILL.md requires a secret env var (AGENTMEMO_ADMIN_KEY) even though the registry metadata lists no required env — an inconsistency worth verifying.

Install Mechanism

Registry lists no install spec (instruction-only), which is lower risk, but the bundle actually contains full source code, requirements.txt and install.sh scripts. SKILL.md recommends pip install -r requirements.txt and warns about a ~90MB model download from HuggingFace. No remote arbitrary binary downloads are specified, but the presence of install scripts and full source means you will be running code on your machine — inspect requirements.txt and scripts before installing.

Credentials

The SKILL.md requires AGENTMEMO_ADMIN_KEY (secret) and documents other optional env vars (port, DB path, rate limits), but the registry metadata reports no required env vars or primary credential. This mismatch is an incoherence that could confuse permissioning and automated deployments. Requesting one service-specific secret (admin API key) is reasonable for a kiosk memory server, but confirm the key is stored/handled securely and not transmitted elsewhere.

Persistence & Privilege

always:false and normal autonomous invocation defaults are used. The skill does persist data (SQLite DB, cached embeddings, model cache under ~/.cache) — expected for a memory server. Nothing requests system-wide privileges or modifications to other skills' configs.

What to consider before installing

This package implements the memory server it claims, but there are incongruities you should verify before installing: - Metadata mismatch: the registry shows no required env vars, but SKILL.md requires AGENTMEMO_ADMIN_KEY (mandatory). Confirm which is authoritative and how your deployment will supply/store that secret. - Inspect files before running: open requirements.txt, install.sh and server.py to ensure no unexpected network calls or shell actions. The first run downloads a ~90MB embedding model from HuggingFace — be prepared for network activity and disk use (~model cache + SQLite DB). - Do not expose the service to the public internet without a reverse proxy and TLS; SKILL.md says it binds to 127.0.0.1 by default, which is good. If you need networked access, put it behind authenticated TLS and rotate the admin key. - Run inside a virtualenv or container; consider setting the DB path and cache locations to a controlled directory and ensure proper file permissions. - If you plan to allow agents to call this autonomously, be careful which agents receive scoped API keys — RBAC is implemented but verify the API-key creation/listing endpoints and ensure keys are not leaked to other subsystems. If you want a safer thumbs-up: ask the publisher for clarification on the required env vars and a short audit of install.sh and server.py (search for unexpected external endpoints, subprocess execution, or code that reads secrets from other paths). If you cannot inspect the code yourself, treat the package as untrusted and run it in an isolated container with limited network access.

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

Variable	Required	Secret	Default	Description
AGENTMEMO_ADMIN_KEY	yes	yes	—	API key for RBAC auth. Server exits if unset.
AGENTMEMO_PORT	no	no	8790	HTTP port (localhost only)
AGENTMEMO_DB	no	no	agentmemo.db	SQLite DB path
AGENTMEMO_RATE_LIMIT	no	no	120	Requests/min per key
AGENTMEMO_POOL_SIZE	no	no	5	DB connection pool size

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

Method	Path	Description
GET	/health	Health check (no auth)
GET	/metrics	Server metrics
GET	/dashboard	Web dashboard
POST	/v1/memories	Store memory
GET	/v1/memories/search	Search (semantic/keyword/hybrid)
PUT	/v1/memories/{id}	Update (creates new version)
DELETE	/v1/memories/{id}	Delete
GET	/v1/memories/{id}/versions	Version history
POST	/v1/memories/{id}/rollback	Rollback to version
POST	/v1/memories/batch	Batch operations
POST	/v1/import	Bulk import
GET	/v1/export	Bulk export
GET	/v1/events/stream	SSE event stream
WS	/v1/ws	WebSocket 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