Semantic memory storage and retrieval using vector embeddings
Arca MCP
A Model Context Protocol (MCP) server providing semantic memory storage and retrieval via vector embeddings. Built with FastAPI + FastMCP, using LanceDB for vector storage and Google Gemini for embedding generation.
Features
- Semantic Search — Store and retrieve memories using natural language queries powered by vector similarity search
- Dual Access — MCP tools for AI agents + REST API for programmatic integrations
- Multi-Tenant Isolation — Namespace-scoped operations via
X-NamespaceHTTP header - Bucket Organization — Group memories into logical buckets for structured storage
- Embedding Caching — Redis-backed cache for generated embeddings to minimize API calls
- Bearer Token Auth — Constant-time token verification for secure access
Prerequisites
- Python 3.14+
- UV package manager
- Redis
- Google API key (for Gemini embeddings)
Quick Start
# Clone the repository
git clone https://github.com/your-org/arca-mcp.git
cd arca-mcp
# Install dependencies
uv sync --locked
# Configure environment
cp .env.example .env
# Edit .env with your ARCA_GOOGLE_API_KEY and ARCA_APP_AUTH_KEY
# Run the server
python -m app
The server starts on http://0.0.0.0:4201 by default, with MCP available at /app/mcp and REST API at /v1.
Configuration
All settings are configured via environment variables with the ARCA_ prefix, or through a .env file.
| Variable | Type | Default | Description |
|---|---|---|---|
ARCA_APP_HOST |
str |
0.0.0.0 |
Server bind address |
ARCA_APP_PORT |
int |
4201 |
Server port |
ARCA_APP_WORKERS |
int |
1 |
Uvicorn worker count |
ARCA_APP_AUTH_KEY |
str |
required | Bearer token for MCP authentication |
ARCA_TRANSPORT |
str |
streamable-http |
MCP transport (stdio, http, sse, streamable-http) |
ARCA_DEBUG |
bool |
false |
Enable debug mode |
ARCA_LOG_MESSAGE_MAX_LEN |
int |
2000 |
Maximum log message length |
ARCA_GOOGLE_API_KEY |
str |
required | Google API key for Gemini embeddings |
ARCA_EMBEDDING_MODEL |
str |
gemini-embedding-001 |
Gemini embedding model name |
ARCA_EMBEDDING_DIMENSION |
int |
3072 |
Embedding vector dimensionality |
ARCA_VECTOR_STORE_PATH |
str |
./lancedb |
LanceDB storage directory |
ARCA_REDIS_HOST |
str |
localhost |
Redis host |
ARCA_REDIS_PORT |
int |
6379 |
Redis port |
ARCA_REDIS_DB_CACHE |
int |
4 |
Redis database number for cache |
ARCA_REDIS_PASSWORD |
str |
null |
Redis password (optional) |
ARCA_CACHE_TTL |
int |
3600 |
Default cache TTL in seconds (1 hour) |
ARCA_CACHE_TTL_LONG |
int |
604800 |
Long cache TTL in seconds (7 days, used for embeddings) |
MCP Tools
All tools are mounted under the memory namespace. Operations are scoped to the namespace provided via the X-namespace HTTP header (defaults to "default").
`memory/add`
Store content in memory with a vector embedding.
| Parameter | Type | Required | Description |
|---|---|---|---|
content |
str |
yes | Content to store |
bucket |
str | null |
no | Bucket name (defaults to "default") |
connected_nodes |
list[str] | null |
no | UUIDs of nodes to link at creation time |
relationship_types |
list[str] | null |
no | Parallel relationship labels for connected_nodes |
Returns: { "status": "Memory added", "memory_id": "<uuid>" }
`memory/get`
Retrieve memories via semantic similarity search.
| Parameter | Type | Required | Description |
|---|---|---|---|
query |
str |
yes | Natural language search query |
bucket |
str | null |
no | Filter by bucket |
top_k |
int |
no | Number of results (default: 5) |
Returns: { "status": "Memory retrieved", "results": [...] }
`memory/delete`
Delete a specific memory by its UUID.
| Parameter | Type | Required | Description |
|---|---|---|---|
memory_id |
str |
yes | UUID of the memory to delete |
Returns: { "status": "Memory deleted" }
`memory/clear`
Clear all memories in a bucket.
| Parameter | Type | Required | Description |
|---|---|---|---|
bucket |
str | null |
no | Bucket to clear (defaults to "default") |
Returns: { "status": "Memories cleared" }
`memory/list_buckets`
List all buckets in the current namespace.
Parameters: None
Returns: { "buckets": ["default", "work", ...] }
`memory/connect`
Create a directed edge between two memory nodes.
| Parameter | Type | Required | Description |
|---|---|---|---|
source_id |
str |
yes | UUID of the source node |
target_id |
str |
yes | UUID of the target node |
relationship_type |
str |
yes | Edge label (e.g. "related_to", "depends_on") |
Returns: { "status": "Memories connected" }
`memory/disconnect`
Remove one or all directed edges between two nodes.
| Parameter | Type | Required | Description
Tools (7)
memory/addStore content in memory with a vector embedding.memory/getRetrieve memories via semantic similarity search.memory/deleteDelete a specific memory by its UUID.memory/clearClear all memories in a bucket.memory/list_bucketsList all buckets in the current namespace.memory/connectCreate a directed edge between two memory nodes.memory/disconnectRemove one or all directed edges between two nodes.Environment Variables
ARCA_APP_AUTH_KEYrequiredBearer token for MCP authenticationARCA_GOOGLE_API_KEYrequiredGoogle API key for Gemini embeddingsARCA_APP_HOSTServer bind addressARCA_APP_PORTServer portConfiguration
{"mcpServers": {"arca": {"command": "python", "args": ["-m", "app"], "env": {"ARCA_GOOGLE_API_KEY": "your_key", "ARCA_APP_AUTH_KEY": "your_token"}}}}