Memex

What ayushagrawal288/memex MCP server does

The ayushagrawal288/memex MCP server gives AI agents persistent storage for facts, preferences, past events, and procedures. It stores memories for an agent and user, generates an embedding locally, and saves the record in PostgreSQL with pgvector. Agents can then search those records semantically instead of receiving only the most recent or exact-text matches.

Memory records support three types: episodic for events and conversations, semantic for facts and preferences, and procedural for workflows or instructions. The service also supports deleting a memory and counting memories associated with an agent or user.

How it works

On a write, the service passes the memory content through fastembed using the local BAAI/bge-small-en-v1.5 ONNX model. The resulting 384-dimensional vector is inserted into PostgreSQL. No external embedding request is needed.

On a search, the query is embedded with the same local model. PostgreSQL uses a cosine-similarity pgvector query to select three times the requested number of candidates. Python then reranks those candidates using a configurable blend of semantic similarity and age:

score = α × cosine_similarity + (1 − α) × exp(−λ × age_days)

The default semantic-weight parameter is alpha=0.7, and the default recency half-life is 30 days. Higher alpha values favor semantic similarity; lower values give recency more influence. The database uses an ivfflat index, intended by the project for small-to-medium collections.

Setup and configuration

The ayushagrawal288/memex MCP server is designed to run locally with Docker and Docker Compose. Clone the repository, change into its directory, and run docker compose up. The REST API is available at http://localhost:8000, with interactive documentation at /docs. The project also contains an MCP FastAPI process configured on port 8001 and identifies its MCP transport as Streamable HTTP.

The stack includes PostgreSQL 16, the pgvector extension, and an asyncpg connection pool. The default pool limits are five minimum and 20 maximum connections; DB_MAX_POOL_SIZE can override the maximum. The README states that no API keys are required and that the complete stack runs locally.

Tools and capabilities

The MCP tool definitions cover four operations:

• Store a memory
• Search memories
• Delete a memory
• Count memories

The corresponding REST API provides memory creation, search, deletion, and count routes. Health and readiness checks are available, and a metrics endpoint exposes Prometheus metrics. The repository also includes background summarization using a local extractive summarizer based on deduplication and term-frequency scoring.

Limitations and notes

Local ONNX inference is required for both writes and searches, so CPU capacity affects throughput. Reported tests used a MacBook M-series machine with Docker Desktop and found roughly 120 requests per second in aggregate under the stated test configuration; saturation caused multi-second latency. These figures are environment-specific rather than a service guarantee.

The ivfflat configuration is aimed at collections below about one million vectors. The project notes that larger deployments may benefit from moving scoring into PostgreSQL, changing to HNSW, adding embedding caching, or scaling horizontally. Those approaches are described as future or scaling options, not default behavior.

The ayushagrawal288/memex MCP server does not provide a hosted cloud dependency in the documented setup. Deployers remain responsible for running Docker, PostgreSQL, and the service processes.