14 KiB
14 KiB
| sidebar_position |
|---|
| 6 |
Server Administration
Guide to deploying and configuring the Memora server.
Architecture Overview
┌─────────────────────────────────────────────────────────────────────────────┐
│ CLIENTS │
├─────────────────┬─────────────────┬─────────────────┬───────────────────────┤
│ Python Client │ Node.js Client │ CLI │ AI Assistants │
│ memora-client │ @memora/client │ memora-cli │ (Claude, etc.) │
└────────┬────────┴────────┬────────┴────────┬────────┴───────────┬───────────┘
│ │ │ │
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ MEMORA API SERVER │
│ (localhost:8080) │
├─────────────────────────────────┬───────────────────────────────────────────┤
│ HTTP API │ MCP API │
│ /api/memories/* │ MCP Server (stdio) │
│ /api/agents/* │ memora_search, memora_think, │
│ /api/search, /api/think │ memora_store, memora_agents │
└─────────────────────────────────┴───────────────────────────────────────────┘
│ │
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ PROCESSING PIPELINE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ INGESTION │ │ RETRIEVAL │ │ REASONING │ │
│ │ │ │ (TEMPR) │ │ (CARA) │ │
│ │ LLM Extract │ │ │ │ │ │
│ │ Entity Res. │ │ 4-way Search│ │ Personality │ │
│ │ Graph Build │ │ RRF Fusion │ │ Opinion Gen │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ ML MODELS │
├───────────────────┬───────────────────┬─────────────────────────────────────┤
│ Embeddings │ Cross-Encoder │ LLM Provider │
│ all-MiniLM-L6-v2 │ ms-marco-MiniLM │ OpenAI / Groq / Ollama │
│ (384-dim) │ (reranking) │ (extraction, reasoning) │
└───────────────────┴───────────────────┴─────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ POSTGRESQL + PGVECTOR │
│ (localhost:5432) │
├─────────────────────────────────────────────────────────────────────────────┤
│ • Memory Units (facts, opinions) • HNSW Vector Index │
│ • Entity Graph (nodes, edges) • GIN Full-Text Index │
│ • Agent Profiles • Temporal Indexes │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ CONTROL PLANE (Optional) │
│ (localhost:3000) │
├─────────────────────────────────────────────────────────────────────────────┤
│ • Web UI for administration • Agent management │
│ • Memory visualization • Graph explorer │
│ • Connects to API Server • Monitoring dashboard │
└─────────────────────────────────────────────────────────────────────────────┘
Quick Start
Docker (Recommended)
# Clone the repository
git clone https://github.com/memora/memora.git
cd memora
# Create environment file
cp .env.example .env
# Edit .env with your LLM API key
# Start all services
cd docker
./start.sh
Services will be available at:
- API Server: http://localhost:8080
- Control Plane: http://localhost:3000
- Swagger UI: http://localhost:8080/docs
Local Development
# Install dependencies
uv sync
# Start PostgreSQL only (via Docker)
cd docker && docker-compose up -d postgres
# Start the API server
./scripts/start-server.sh --env local
Environment Variables
API Server (MEMORA_API_*)
| Variable | Description | Default |
|---|---|---|
MEMORA_API_DATABASE_URL |
PostgreSQL connection string | Required |
MEMORA_API_LLM_PROVIDER |
LLM provider: openai, groq, ollama |
groq |
MEMORA_API_LLM_API_KEY |
API key for LLM provider | Required (except ollama) |
MEMORA_API_LLM_MODEL |
Model name | openai/gpt-oss-20b |
MEMORA_API_LLM_BASE_URL |
Custom LLM endpoint | Provider default |
MEMORA_API_HOST |
Server bind address | 0.0.0.0 |
MEMORA_API_PORT |
Server port | 8080 |
MEMORA_API_MCP_ENABLED |
Enable MCP server | true |
Control Plane (MEMORA_CP_*)
| Variable | Description | Default |
|---|---|---|
MEMORA_CP_DATAPLANE_API_URL |
API server URL | http://localhost:8080 |
MEMORA_CP_HOSTNAME |
Server bind address | 0.0.0.0 |
MEMORA_CP_PORT |
Server port | 3000 |
Example Configuration
# .env file
# Database
MEMORA_API_DATABASE_URL=postgresql://memora:memora_dev@localhost:5432/memora
# LLM - Using Groq (fast inference)
MEMORA_API_LLM_PROVIDER=groq
MEMORA_API_LLM_API_KEY=gsk_xxxxxxxxxxxx
MEMORA_API_LLM_MODEL=llama-3.1-70b-versatile
# LLM - Using OpenAI
# MEMORA_API_LLM_PROVIDER=openai
# MEMORA_API_LLM_API_KEY=sk-xxxxxxxxxxxx
# MEMORA_API_LLM_MODEL=gpt-4o
# LLM - Using Ollama (local, no API key)
# MEMORA_API_LLM_PROVIDER=ollama
# MEMORA_API_LLM_BASE_URL=http://localhost:11434/v1
# MEMORA_API_LLM_MODEL=llama3.1
# Control Plane
MEMORA_CP_DATAPLANE_API_URL=http://localhost:8080
ML Models
Memora uses several ML models for different stages of the pipeline:
Embedding Model
| Model | Dimensions | Purpose |
|---|---|---|
all-MiniLM-L6-v2 |
384 | Semantic vector embeddings |
Downloaded automatically on first run. Used for:
- Memory vectorization
- Query embedding
- Semantic similarity search
Cross-Encoder (Reranking)
| Model | Purpose |
|---|---|
cross-encoder/ms-marco-MiniLM-L-6-v2 |
Neural reranking |
Reranks search results for precision after initial retrieval. Includes temporal context in input.
Temporal Parser
| Model | Purpose |
|---|---|
t5-small |
Temporal expression parsing |
Parses natural language time expressions like "last spring" or "in June 2024".
LLM (Configurable)
Used for:
- Fact extraction from raw content
- Entity extraction and resolution
- Opinion generation with personality
- Think/reasoning responses
Supported providers:
- OpenAI: GPT-4, GPT-4o, GPT-3.5-turbo
- Groq: Llama 3.1, Mixtral (fast inference)
- Ollama: Any local model
Database Schema
PostgreSQL with pgvector extension:
-- Memory units (facts and opinions)
CREATE TABLE memory_units (
id UUID PRIMARY KEY,
agent_id VARCHAR NOT NULL,
text TEXT NOT NULL,
fact_type VARCHAR NOT NULL, -- 'world', 'agent', 'opinion'
confidence_score FLOAT,
embedding VECTOR(384),
occurred_start DATE,
occurred_end DATE,
mentioned_at TIMESTAMP,
context VARCHAR,
document_id VARCHAR
);
-- Entity graph
CREATE TABLE entities (
id UUID PRIMARY KEY,
agent_id VARCHAR NOT NULL,
name VARCHAR NOT NULL,
entity_type VARCHAR NOT NULL,
canonical_name VARCHAR
);
CREATE TABLE entity_links (
memory_id UUID REFERENCES memory_units(id),
entity_id UUID REFERENCES entities(id),
PRIMARY KEY (memory_id, entity_id)
);
-- Agent profiles
CREATE TABLE agent_profiles (
agent_id VARCHAR PRIMARY KEY,
background TEXT,
openness FLOAT DEFAULT 0.5,
conscientiousness FLOAT DEFAULT 0.5,
extraversion FLOAT DEFAULT 0.5,
agreeableness FLOAT DEFAULT 0.5,
neuroticism FLOAT DEFAULT 0.5,
bias_strength FLOAT DEFAULT 0.5
);
Indexes
- HNSW Index: Fast approximate nearest neighbor for vector search
- GIN Index: Full-text search with BM25 ranking
- B-tree Indexes: Agent ID, timestamps, entity lookups
Docker Services
services:
postgres: # pgvector/pgvector:pg16
api: # Memora API server
control-plane: # Admin UI (optional)
Commands
# Start all services
cd docker && ./start.sh
# Stop services
cd docker && ./stop.sh
# Clean all data
cd docker && ./clean.sh
# View logs
docker-compose logs -f api
docker-compose logs -f control-plane
Health Checks
API Server
curl http://localhost:8080/api/v1/agents
Control Plane
curl http://localhost:3000/
Production Deployment
For production deployments:
- Use managed PostgreSQL with pgvector extension
- Set proper secrets via environment variables or secrets manager
- Configure resource limits for ML model inference
- Set up monitoring for API latency and error rates
- Use HTTPS with proper TLS certificates
- Configure rate limiting at load balancer level
Resource Requirements
| Component | CPU | Memory | Notes |
|---|---|---|---|
| API Server | 2+ cores | 4GB+ | ML models loaded in memory |
| PostgreSQL | 2+ cores | 4GB+ | Depends on data size |
| Control Plane | 1 core | 512MB | Lightweight Next.js app |