The memex server provides a persistent memory service for AI agents, enabling them to store, search, delete, and count memories using semantic search with recency decay. It exposes both a REST API and an MCP (Model Context Protocol) server for integration with MCP-aware agents like Claude Desktop/Code.
Store memories (store_memory): Embed and persist text memories for a specific agent/user pair, tagged as episodic, semantic, or procedural, with a configurable importance weight (0.0–2.0) and max content length of 8000 characters.
Search memories (search_memories): Retrieve top-k memories ranked by a blend of semantic similarity and recency decay. The alpha parameter is configurable per request (1.0 = pure semantic, 0.0 = pure recency), with optional memory type filtering and up to 50 results.
Delete a memory (delete_memory): Remove a specific memory by UUID, with ownership enforced per agent.
Count memories (count_memories): Query the total number of memories for a given agent/user pair.
Memory summarisation: A background task automatically condenses old episodic memories into semantic summaries using a local extractive algorithm, deleting the originals.
Health check: A /health endpoint reports server liveness and database connectivity.
Observability: A /metrics endpoint exposes Prometheus metrics covering request latency, embedding performance, and DB pool utilisation.
A production-grade persistent memory service for AI agents. Agents forget everything between sessions by default — memex fixes that. It stores, retrieves, and ranks conversation memory using semantic search with recency decay, so agents surface what's relevant and recent, not just what's semantically closest.
POST /v1/memories → store a memory, embed it, persist to Postgres
POST /v1/memories/search → retrieve top-k memories ranked by similarity + recency
DELETE /v1/memories/{id} → forget a specific memory
GET /v1/memories/count → how many memories does this agent/user have
GET /health → liveness + DB connectivity check
GET /metrics → Prometheus metricscaller (agent / app)
│
▼
FastAPI (async)
│
┌────┴────┐
│ │
embeddings asyncpg pool (min=5, max=20)
(fastembed │
ONNX, ▼
local) PostgreSQL 16
pgvector extension
ivfflat index (cosine)Write path: content → fastembed ONNX inference (local, ~12 ms CPU, BAAI/bge-small-en-v1.5) → INSERT with 384-dim vector → return memory ID.
Read path: query → embed → pgvector cosine search (top_k × 3 candidates) → re-rank with recency decay in Python → return top_k results with scores.
Related MCP server: Memsolus MCP Server
Pure vector similarity returns the most semantically similar memories, not the most useful ones. A fact from 90 days ago that's a 0.95 similarity match is often less useful than a 0.80 match from yesterday.
Score formula:
score = α × cosine_similarity + (1 − α) × exp(−λ × age_days)Where λ = ln(2) / half_life_days (default: 30 days, so a 30-day-old memory has 50% recency weight).
α is configurable per request (default 0.7). Task-focused agents use higher α (semantic dominates). Conversational agents use lower α (recency matters more).
The pgvector query returns top_k × 3 candidates sorted by pure similarity. Python re-ranks with the decay formula and slices to top_k. This prevents recency decay from starving high-similarity older memories — they're still in the candidate pool.
At 10× scale (>1M memories per agent): push the scoring into a Postgres function using pg_proc to eliminate the Python re-ranking round-trip.
SQLAlchemy adds ORM overhead on every query. The hot retrieval path — embed, query, re-rank — needs to be tight. asyncpg gives direct control over pool min/max (same instinct as tuning HikariCP in Java). pgvector queries require raw SQL for the <=> operator anyway.
Pool defaults: min=5, max=20. Right-size for a single-instance deployment. Override via DB_MAX_POOL_SIZE env var.
Sliding window counter via upsert. One fewer dependency. Correct under concurrent requests (transactional upsert). At 10× scale with distributed deployments: replace with Redis INCR + EXPIRE — atomic operations, no lock contention.
ivfflat has lower build cost and lower memory footprint — the right tradeoff at small-to-medium scale (<1M vectors). lists=100 works well up to ~1M rows. At 10× scale: switch to HNSW (m=16, ef_construction=64) for better recall at the cost of higher memory and build time.
Prerequisites: Docker and Docker Compose. No API keys required — the entire stack runs locally.
git clone https://github.com/ayushagrawal288/memex
cd memex
docker compose upThe API is live at http://localhost:8000. Interactive docs at http://localhost:8000/docs.
curl -X POST http://localhost:8000/v1/memories \
-H "Content-Type: application/json" \
-d '{
"agent_id": "my-agent",
"user_id": "user-123",
"content": "User prefers concise responses and dislikes verbose explanations.",
"memory_type": "semantic",
"importance": 1.2
}'{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"agent_id": "my-agent",
"user_id": "user-123",
"content": "User prefers concise responses and dislikes verbose explanations.",
"importance": 1.2,
"memory_type": "semantic",
"created_at": "2026-05-26T10:30:00Z",
"score": null
}curl -X POST http://localhost:8000/v1/memories/search \
-H "Content-Type: application/json" \
-d '{
"agent_id": "my-agent",
"user_id": "user-123",
"query": "how does this user like to communicate",
"top_k": 5,
"alpha": 0.7
}'{
"results": [
{
"id": "3fa85f64-...",
"content": "User prefers concise responses and dislikes verbose explanations.",
"memory_type": "semantic",
"created_at": "2026-05-26T10:30:00Z",
"score": 0.8921
}
],
"query": "how does this user like to communicate",
"total": 1
}Type | Use for |
| Specific events, past conversations |
| Facts, preferences, general knowledge |
| Workflows, how-to instructions |
Run on a MacBook M-series, Docker Desktop, single Postgres instance:
locust -f scripts/load_test.py --host=http://localhost:8000 \
--headless -u 50 -r 10 -t 60sRealistic load (50 users, 100–300 ms think time — models actual agent traffic):
Endpoint | RPS | p50 (ms) | p95 (ms) | p99 (ms) | Error rate |
POST /v1/memories (write) | 27 | 160 | 270 | 330 | 0% |
POST /v1/memories/search | 83 | 110 | 200 | 250 | 0% |
Aggregated | 113 | 120 | 230 | 300 | 0% |
Saturation test (500 users, minimal think time — finds the throughput ceiling):
Endpoint | RPS (plateau) | p50 (ms) | p99 (ms) | Error rate |
POST /v1/memories (write) | 28 | 3,900 | 6,100 | 0% |
POST /v1/memories/search | 91 | 3,600 | 5,800 | 0% |
Aggregated | ~120 | 3,700 | 5,900 | 0% |
Run on MacBook M-series, Docker Desktop (4 CPUs), 4 uvicorn workers, 16 threads/worker.
Embeddings: local ONNX (BAAI/bge-small-en-v1.5) — zero external API calls, zero cost.
Why the ceiling is ~120 RPS:
Every write and every search requires one ONNX inference (~10–15 ms on CPU). With 4 Docker CPUs: 4 cores / 12 ms ≈ 333 embeddings/s theoretical max. After Python overhead, DB queries, and asyncio scheduling: ~120 RPS actual.
Path to higher throughput:
Approach | Expected gain | Complexity |
Embedding cache (Redis, key = SHA256 of text) | 2–3× (40–60% hit rate on repeated agent queries) | Low |
Horizontal scaling (N replicas behind a load balancer) | N× linear | Medium |
GPU inference (swap ONNX runtime → CUDA) | 10–50× | Medium |
Voyage-3 API (offload to Anthropic's inference fleet) | Scales to thousands of RPS, limited by API quota | Low code change |
memex/
├── app/
│ ├── main.py # REST API — FastAPI, lifespan, router registration
│ ├── mcp_server.py # MCP server — single-worker FastAPI on port 8001
│ ├── core/
│ │ └── config.py # All settings, loaded from env
│ ├── db/
│ │ └── pool.py # asyncpg pool, migrations
│ ├── models/
│ │ └── schemas.py # Pydantic request/response models
│ ├── services/
│ │ ├── embeddings.py # fastembed ONNX inference (local, zero API calls)
│ │ ├── local_summarizer.py # Extractive summariser — Jaccard dedup + TF scoring
│ │ ├── memory.py # Core write/search/scoring logic
│ │ ├── metrics.py # Prometheus metric definitions
│ │ ├── summarizer.py # Background summarisation job
│ │ └── rate_limit.py # Sliding window rate limiter
│ └── api/routes/
│ ├── memories.py # Memory endpoints
│ ├── health.py # Health + readiness
│ └── mcp_tools.py # MCP tool definitions (store, search, delete, count)
├── scripts/
│ └── load_test.py # Locust load test
├── docker-compose.yml
├── Dockerfile
└── requirements.txtdocker compose up starts Prometheus and Grafana alongside the API:
Service | URL | Credentials |
REST API docs | — | |
MCP server | — | |
Prometheus | — | |
Grafana | admin / admin |
The Grafana dashboard is provisioned automatically. Panels:
HTTP request rate + latency p50/p99 — from prometheus-fastapi-instrumentator
Embedding API latency p50/p99 — per-attempt histogram by operation (embed / embed_batch)
Memory operations/s — create, search, delete throughput
DB pool utilisation — active vs idle connections (update interval: 15 s)
Summariser activity — memories condensed per hour, run outcomes
Embedding errors/min — by operation and error type
Custom metrics are in app/services/metrics.py and exposed on /metrics alongside the standard FastAPI instrumentator metrics.
memex exposes itself as an MCP server so any MCP-aware agent (Claude Desktop, Claude Code, custom agents) can store and retrieve memories without custom HTTP integration.
Transport: Streamable HTTP (MCP 2024-11-05 spec). Single-worker process on port 8001 — session state is in-process, so a separate service avoids sticky-session complexity while keeping the REST API's multi-worker throughput.
Tools:
Tool | Description |
| Embed + persist a memory (type, importance configurable) |
| Semantic + recency ranked retrieval with configurable alpha |
| Forget a specific memory by UUID |
| How many memories an agent/user pair has |
Add to ~/.config/claude/claude_desktop_config.json:
{
"mcpServers": {
"memex": {
"type": "streamable-http",
"url": "http://localhost:8001/mcp/"
}
}
}claude mcp add --transport http memex http://localhost:8001/mcp/The MCP Streamable HTTP transport is session-stateful — initialize, tools/list, and tools/call must all reach the same server process. The REST API runs 4 uvicorn workers with round-robin routing; routing different MCP requests to different workers breaks session state.
Running a dedicated single-worker MCP service on port 8001 avoids sticky-session infrastructure (nginx ip_hash, Redis session store) while keeping the REST API fully multi-worker.
Runs as a background asyncio task on a configurable interval (default: every 5 minutes). Finds any (agent_id, user_id) pair where episodic memory count exceeds a threshold, condenses the oldest batch into a single semantic memory, then deletes the originals. Fully local — no LLM API calls.
How it summarises: Pure Python extractive algorithm. Sentences are deduplicated by Jaccard similarity (≥ 0.7 threshold), scored by word frequency (TF), and the top-N are returned in original order. ~1 ms per summarisation, zero dependencies beyond the standard library.
Why episodic-only: Episodic memories are conversation events with natural time-based obsolescence. Semantic and procedural memories encode facts and skills — silently condensing them risks precision loss; they age out via recency decay instead.
Concurrency safety: Uses pg_try_advisory_xact_lock keyed on hashtext(agent_id|user_id). The lock is held only during the DB write transaction, not during the embedding call.
Tune via env vars:
Var | Default | Description |
|
| Toggle the background job |
|
| Episodic count to trigger per pair |
|
| Oldest N memories to condense per run |
|
| How often the job wakes up |
Memory summarisation — background job to condense old episodic memories (local extractive algorithm, zero API calls) when count exceeds threshold
Prometheus + Grafana — p50/p99 latency dashboards, embedding API call duration, pool saturation
MCP-compatible endpoint — Streamable HTTP server on port 8001; 4 tools (store, search, delete, count); connects to Claude Desktop and Claude Code
HNSW index option — flag to switch from ivfflat to HNSW for deployments with >1M vectors
Importance-weighted retrieval — factor importance score into ranking formula alongside similarity and recency
Layer | Choice | Why |
API | FastAPI + uvicorn | Async-first, fast, excellent OpenAPI generation |
Embeddings | fastembed ONNX ( | Local, zero API calls, ~12 ms CPU inference, 384-dim |
Database | PostgreSQL 16 + pgvector | Relational + vector in one system, no extra infra |
Vector index | ivfflat | Lower build cost than HNSW at this scale |
Pool | asyncpg | Direct control, zero ORM overhead |
Summariser | Pure Python extractive | Jaccard dedup + TF scoring, zero ML deps, ~1 ms |
Retry | tenacity | Jitter-based backoff on transient errors |
Metrics | Prometheus + prometheus-fastapi-instrumentator | Standard observability |
Load testing | Locust | Python-native, realistic user simulation |
Return the total number of stored memories for an agent/user pair.
Args:
agent_id: Agent identifier.
user_id: User identifier.
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | ||
| user_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It implies a read operation but omits details on error handling, rate limits, or behavior for missing agent/user pairs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus Args list, front-loaded with the main purpose. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple count tool with output schema, description covers core purpose. Could mention return format, but output schema likely handles that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage; description adds 'Agent identifier' and 'User identifier', clarifying the purpose beyond schema titles. Minimal but adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Return', resource 'total number of stored memories', and scope 'for an agent/user pair'. Distinct from sibling tools (delete, search, store).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use count_memories versus alternatives like search_memories or store_memory. Lacks context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a specific memory by ID. The agent_id is used as an ownership check —
agents cannot delete each other's memories.
Args:
agent_id: Agent that owns the memory.
memory_id: UUID of the memory to delete (from store_memory or search_memories).
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | ||
| memory_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral disclosure. It mentions the ownership check and deletion, but does not describe idempotency, error states, or return values (though output schema exists).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with a clear structure: one-line summary followed by parameter descriptions. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple delete operation and presence of an output schema, the description is almost complete. It could mention idempotency or confirmation, but the existing details (ownership check, parameter sources) suffice.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaningful explanations: agent_id is 'Agent that owns the memory' and memory_id is 'UUID of the memory to delete (from store_memory or search_memories)'. This compensates fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a specific memory by ID', which is a specific verb-resource pair. It distinguishes from sibling tools (store, search, count) by specifying deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context on usage by stating 'agents cannot delete each other's memories', implying a constraint. However, it does not explicitly state when to use this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search memories using semantic similarity + recency decay. Returns top-k
ranked results with scores.
Args:
agent_id: Agent whose memories to search.
user_id: User whose memories to search.
query: Natural language description of what to recall.
top_k: Number of memories to return (1–50). Default: 5.
alpha: Blend weight 0.0–1.0. 1.0 = pure semantic, 0.0 = pure recency.
Default: 0.7.
memory_type: Filter to 'episodic', 'semantic', or 'procedural'. Omit to search all.
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | ||
| user_id | Yes | ||
| query | Yes | ||
| top_k | No | ||
| alpha | No | ||
| memory_type | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the ranking mechanism and blend weight, but without annotations, it lacks details on side effects, authentication, rate limits, or behavior when no results are found. It adequately describes the core functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with a docstring format. It front-loads the purpose and lists parameters clearly. Could be slightly more concise, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description focuses adequately on input parameters. It covers required and optional parameters with defaults. Missing details like pagination or error handling, but sufficient for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides detailed explanations for all parameters, including the meaning of alpha (blend weight) and memory_type filter options. Schema coverage is 0%, so the description adds significant value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches memories using semantic similarity and recency decay, returning top-k ranked results with scores. It distinguishes itself from sibling tools like store_memory, delete_memory, and count_memories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the parameters and default values but does not provide explicit guidance on when to use this tool versus alternatives. No 'use when' or 'avoid when' instructions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store a memory for an agent/user pair. Content is embedded locally (ONNX)
and persisted to Postgres. Returns the memory ID on success.
Args:
agent_id: Unique identifier for the agent storing the memory.
user_id: Unique identifier for the user this memory belongs to.
content: The text to remember (max 8000 chars).
memory_type: 'episodic' (events/conversations), 'semantic' (facts/preferences),
or 'procedural' (workflows). Default: episodic.
importance: Weight multiplier 0.0–2.0. Use >1.0 for critical facts. Default: 1.0.
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | ||
| user_id | Yes | ||
| content | Yes | ||
| memory_type | No | episodic | |
| importance | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses key behaviors: local embedding via ONNX, persistence to Postgres, response format (memory ID), content length limit (8000 chars), memory type list, and importance range with usage hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet complete: a one-line summary followed by a clear bullet list of parameters. There is no fluff; each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the complexity (5 parameters, 3 required, defaults), the description covers essential behavioral and parameter info. It mentions the output but could be slightly enhanced by noting potential error conditions, though not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema description coverage is 0%, the description must compensate, and it does so thoroughly. It explains each parameter's purpose (agent_id, user_id, content with max chars), enum-like values for memory_type with defaults, and importance with range and recommendation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Store a memory'), the subject ('for an agent/user pair'), and the outcome ('returns the memory ID'). It differentiates from sibling tools (count, delete, search) by being the store operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description details all parameters and defaults, providing implicit usage context (e.g., memory_type options, importance hint). However, it lacks explicit guidance on when to use this tool over alternatives like search_memories or delete_memory.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: storing, searching, counting, and deleting memories. No two tools overlap in functionality, so an agent can easily select the correct one.
All tool names follow a verb_noun pattern in snake_case (store_memory, search_memories, count_memories, delete_memory). The slight plural/singular variation is negligible and does not break consistency.
Four tools is an appropriate number for a focused memory server. Each tool serves a core operation without unnecessary bloat or missing essentials.
The set covers create, read (search and count), and delete operations for memories. An update tool is missing, but that is often handled by delete+store. The lack of a direct get-by-ID tool is a minor gap.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Persistent memory for AI agents — verbatim conversations, searchable by meaning.
Hosted persistent memory with semantic search, importance and TTL for AI agents.
Universal memory for AI agents and tools. Save, organize and search context anywhere.
Persistent memory for AI agents. Semantic search, memory graph, W3C DID identity.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ayushagrawal288/memex'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
