Initial commit: Project foundation and architecture
- Add project requirements document - Add comprehensive architecture design - Add README with quick start guide - Add .gitignore for Python/Docker/Node 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude Code
403
ARCHITECTURE.md
Normal file
403
ARCHITECTURE.md
Normal file
@@ -0,0 +1,403 @@
|
||||
# T6 Mem0 v2 - System Architecture
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Comprehensive memory system for LLM applications based on mem0.ai, featuring MCP server integration, REST API, hybrid storage (Supabase + Neo4j), and OpenAI embeddings.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Client Layer │
|
||||
├──────────────────┬──────────────────┬──────────────────────┤
|
||||
│ Claude Code (MCP)│ N8N Workflows │ External Apps │
|
||||
└──────────────────┴──────────────────┴──────────────────────┘
|
||||
│ │ │
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Interface Layer │
|
||||
├──────────────────────────────┬──────────────────────────────┤
|
||||
│ MCP Server (Port 8765) │ REST API (Port 8080) │
|
||||
│ - SSE Connections │ - FastAPI │
|
||||
│ - MCP Protocol │ - OpenAPI Spec │
|
||||
│ - Tool Registration │ - Auth Middleware │
|
||||
└──────────────────────────────┴──────────────────────────────┘
|
||||
│ │
|
||||
└────────┬───────────┘
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Core Layer │
|
||||
│ Mem0 Core Library │
|
||||
│ - Memory Management - Embedding Generation │
|
||||
│ - Semantic Search - Relationship Extraction │
|
||||
│ - Multi-Agent Support - Deduplication │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌───────────────────┼───────────────────┐
|
||||
▼ ▼ ▼
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ Vector Store │ │ Graph Store │ │ External LLM │
|
||||
│ Supabase │ │ Neo4j │ │ OpenAI │
|
||||
│ (pgvector) │ │ (Cypher) │ │ (Embeddings) │
|
||||
│ 172.21.0.12 │ │ 172.21.0.x │ │ API Cloud │
|
||||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
## Design Decisions
|
||||
|
||||
### 1. MCP Server Approach: Custom Implementation ✅
|
||||
|
||||
**Decision**: Build custom MCP server using mem0 core library with Supabase + Neo4j
|
||||
|
||||
**Rationale**:
|
||||
- Official OpenMemory MCP uses Qdrant (requirement is Supabase)
|
||||
- Community implementations provide good templates but need customization
|
||||
- Custom build ensures exact stack matching and full control
|
||||
|
||||
**Implementation**:
|
||||
- Python-based MCP server using `mcp` library
|
||||
- SSE (Server-Sent Events) for MCP protocol communication
|
||||
- Shares mem0 configuration with REST API
|
||||
|
||||
### 2. Storage Architecture: Hybrid Multi-Store ✅
|
||||
|
||||
**Vector Storage** (Supabase + pgvector):
|
||||
- Semantic search via cosine similarity
|
||||
- 1536-dimensional embeddings (OpenAI text-embedding-3-small)
|
||||
- PostgreSQL with pgvector extension
|
||||
- Connection: `172.21.0.12:5432`
|
||||
|
||||
**Graph Storage** (Neo4j):
|
||||
- Relationship modeling between memory nodes
|
||||
- Entity extraction and connection
|
||||
- Visual exploration via Neo4j Browser
|
||||
- New container on localai network
|
||||
|
||||
**Key-Value Storage** (PostgreSQL JSONB):
|
||||
- Metadata storage in Supabase
|
||||
- Eliminates need for separate Redis
|
||||
- Simplifies infrastructure
|
||||
|
||||
**Why This Works**:
|
||||
- Mem0's hybrid architecture expects multiple stores
|
||||
- Each store optimized for specific query patterns
|
||||
- Supabase handles both vector and structured data
|
||||
- Neo4j specializes in relationship queries
|
||||
|
||||
### 3. API Layer Design: Dual Interface Pattern ✅
|
||||
|
||||
**REST API**:
|
||||
- FastAPI framework
|
||||
- Port: 8080
|
||||
- Authentication: Bearer token
|
||||
- OpenAPI documentation
|
||||
- CRUD operations on memories
|
||||
|
||||
**MCP Server**:
|
||||
- Port: 8765
|
||||
- MCP protocol (SSE transport)
|
||||
- Tool-based interface
|
||||
- Compatible with Claude, Cursor, etc.
|
||||
|
||||
**Shared Core**:
|
||||
- Both use same mem0 configuration
|
||||
- Single source of truth for storage
|
||||
- Consistent behavior across interfaces
|
||||
|
||||
### 4. Docker Networking: LocalAI Network Integration ✅
|
||||
|
||||
**Network**: `localai` (172.21.0.0/16)
|
||||
|
||||
**Services**:
|
||||
```yaml
|
||||
Existing:
|
||||
- Supabase: 172.21.0.12:5432
|
||||
- N8N: (existing container)
|
||||
|
||||
New:
|
||||
- Neo4j: 172.21.0.x:7687 (Bolt) + :7474 (Browser)
|
||||
- REST API: 172.21.0.x:8080
|
||||
- MCP Server: 172.21.0.x:8765
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- All services on same network
|
||||
- Direct container-to-container communication
|
||||
- No host networking complications
|
||||
- Persistent IPs via Docker Compose
|
||||
|
||||
### 5. Phase 1 vs Phase 2: Provider Abstraction ✅
|
||||
|
||||
**Phase 1** (OpenAI):
|
||||
```python
|
||||
config = {
|
||||
"llm": {
|
||||
"provider": "openai",
|
||||
"config": {
|
||||
"model": "gpt-4o-mini",
|
||||
"temperature": 0.1
|
||||
}
|
||||
},
|
||||
"embedder": {
|
||||
"provider": "openai",
|
||||
"config": {
|
||||
"model": "text-embedding-3-small"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Phase 2** (Ollama):
|
||||
```python
|
||||
config = {
|
||||
"llm": {
|
||||
"provider": "ollama",
|
||||
"config": {
|
||||
"model": "llama3.1:8b",
|
||||
"ollama_base_url": "http://172.21.0.1:11434"
|
||||
}
|
||||
},
|
||||
"embedder": {
|
||||
"provider": "ollama",
|
||||
"config": {
|
||||
"model": "nomic-embed-text"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Strategy**:
|
||||
- Configuration-driven provider selection
|
||||
- Environment variable overrides
|
||||
- No code changes for provider swap
|
||||
- Mem0 natively supports both providers
|
||||
|
||||
## Component Details
|
||||
|
||||
### Mem0 Configuration
|
||||
|
||||
```python
|
||||
from mem0 import Memory
|
||||
|
||||
config = {
|
||||
# Vector Store
|
||||
"vector_store": {
|
||||
"provider": "supabase",
|
||||
"config": {
|
||||
"connection_string": "postgresql://user:pass@172.21.0.12:5432/postgres",
|
||||
"collection_name": "t6_memories",
|
||||
"embedding_model_dims": 1536,
|
||||
"index_method": "hnsw",
|
||||
"index_measure": "cosine_distance"
|
||||
}
|
||||
},
|
||||
|
||||
# Graph Store
|
||||
"graph_store": {
|
||||
"provider": "neo4j",
|
||||
"config": {
|
||||
"url": "neo4j://172.21.0.x:7687",
|
||||
"username": "neo4j",
|
||||
"password": "${NEO4J_PASSWORD}"
|
||||
}
|
||||
},
|
||||
|
||||
# LLM Provider
|
||||
"llm": {
|
||||
"provider": "openai",
|
||||
"config": {
|
||||
"model": "gpt-4o-mini",
|
||||
"temperature": 0.1,
|
||||
"max_tokens": 2000
|
||||
}
|
||||
},
|
||||
|
||||
# Embedder
|
||||
"embedder": {
|
||||
"provider": "openai",
|
||||
"config": {
|
||||
"model": "text-embedding-3-small",
|
||||
"embedding_dims": 1536
|
||||
}
|
||||
},
|
||||
|
||||
# Version
|
||||
"version": "v1.1"
|
||||
}
|
||||
|
||||
memory = Memory.from_config(config_dict=config)
|
||||
```
|
||||
|
||||
### REST API Endpoints
|
||||
|
||||
```
|
||||
POST /v1/memories/ - Add new memory
|
||||
GET /v1/memories/{id} - Get specific memory
|
||||
GET /v1/memories/search - Search memories
|
||||
PATCH /v1/memories/{id} - Update memory
|
||||
DELETE /v1/memories/{id} - Delete memory
|
||||
GET /v1/memories/user/{id} - Get user memories
|
||||
GET /v1/health - Health check
|
||||
GET /v1/stats - System statistics
|
||||
```
|
||||
|
||||
### MCP Server Tools
|
||||
|
||||
```
|
||||
add_memory - Add new memory to system
|
||||
search_memories - Search memories by query
|
||||
get_memory - Retrieve specific memory
|
||||
update_memory - Update existing memory
|
||||
delete_memory - Remove memory
|
||||
list_user_memories - List all memories for user
|
||||
get_memory_graph - Visualize memory relationships
|
||||
```
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Adding a Memory
|
||||
|
||||
```
|
||||
1. Client → MCP/REST API
|
||||
POST memory data with user_id
|
||||
|
||||
2. Interface Layer → Mem0 Core
|
||||
Validate and process request
|
||||
|
||||
3. Mem0 Core → OpenAI
|
||||
Generate embeddings (1536-dim vector)
|
||||
|
||||
4. Mem0 Core → Supabase
|
||||
Store vector + metadata in PostgreSQL
|
||||
|
||||
5. Mem0 Core → Neo4j
|
||||
Extract entities and relationships
|
||||
Create nodes and edges in graph
|
||||
|
||||
6. Response → Client
|
||||
Return memory_id and confirmation
|
||||
```
|
||||
|
||||
### Searching Memories
|
||||
|
||||
```
|
||||
1. Client → MCP/REST API
|
||||
Search query + filters (user_id, etc.)
|
||||
|
||||
2. Interface Layer → Mem0 Core
|
||||
Process search request
|
||||
|
||||
3. Mem0 Core → OpenAI
|
||||
Generate query embedding
|
||||
|
||||
4. Mem0 Core → Supabase
|
||||
Vector similarity search (cosine)
|
||||
Retrieve top-k matches
|
||||
|
||||
5. Mem0 Core → Neo4j
|
||||
Fetch related graph context
|
||||
Enrich results with relationships
|
||||
|
||||
6. Response → Client
|
||||
Ranked results with relevance scores
|
||||
```
|
||||
|
||||
## Performance Characteristics
|
||||
|
||||
Based on mem0.ai research findings:
|
||||
|
||||
- **Accuracy**: 26% improvement over baseline OpenAI
|
||||
- **Latency**: 91% lower p95 than full-context approaches
|
||||
- **Token Efficiency**: 90% reduction via selective memory retrieval
|
||||
- **Storage**: Hybrid approach optimal for different query patterns
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Authentication
|
||||
- Bearer token authentication for REST API
|
||||
- MCP server uses client-specific SSE endpoints
|
||||
- Tokens stored in environment variables
|
||||
|
||||
### Data Privacy
|
||||
- All data stored locally (Supabase + Neo4j)
|
||||
- No cloud sync or external storage
|
||||
- User isolation via user_id filtering
|
||||
|
||||
### Network Security
|
||||
- Services on private Docker network
|
||||
- No public exposure (use reverse proxy if needed)
|
||||
- Internal communication only
|
||||
|
||||
## Scalability Considerations
|
||||
|
||||
### Horizontal Scaling
|
||||
- REST API: Multiple containers behind load balancer
|
||||
- MCP Server: Dedicated instances per client group
|
||||
- Mem0 Core: Stateless, scales with API containers
|
||||
|
||||
### Vertical Scaling
|
||||
- Supabase: PostgreSQL connection pooling
|
||||
- Neo4j: Memory configuration tuning
|
||||
- Vector indexing: HNSW for performance
|
||||
|
||||
## Monitoring & Observability
|
||||
|
||||
### Metrics
|
||||
- Memory operations (add/search/delete) per second
|
||||
- Average response time
|
||||
- Vector store query latency
|
||||
- Graph query complexity
|
||||
- Token usage (OpenAI API)
|
||||
|
||||
### Logging
|
||||
- Structured logging (JSON)
|
||||
- Request/response tracking
|
||||
- Error aggregation
|
||||
- Performance profiling
|
||||
|
||||
## Migration Path to Phase 2 (Ollama)
|
||||
|
||||
### Changes Required
|
||||
1. Update configuration to use Ollama provider
|
||||
2. Deploy Ollama container on localai network
|
||||
3. Pull required models (llama3.1, nomic-embed-text)
|
||||
4. Update embedding dimensions if needed
|
||||
5. Test and validate performance
|
||||
|
||||
### No Changes Required
|
||||
- Storage layer (Supabase + Neo4j)
|
||||
- API interfaces (REST + MCP)
|
||||
- Docker networking
|
||||
- Client integrations
|
||||
|
||||
## Technology Stack Summary
|
||||
|
||||
| Layer | Technology | Version | Purpose |
|
||||
|-------|-----------|---------|---------|
|
||||
| Core | mem0ai | latest | Memory management |
|
||||
| Vector DB | Supabase (pgvector) | existing | Semantic search |
|
||||
| Graph DB | Neo4j | 5.x | Relationships |
|
||||
| LLM | OpenAI API | latest | Embeddings + reasoning |
|
||||
| REST API | FastAPI | 0.115+ | HTTP interface |
|
||||
| MCP Server | Python MCP SDK | latest | MCP protocol |
|
||||
| Containerization | Docker Compose | latest | Orchestration |
|
||||
| Documentation | Mintlify | latest | Docs site |
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Initialize Git repository
|
||||
2. Set up Docker Compose configuration
|
||||
3. Configure Supabase migrations (pgvector + tables)
|
||||
4. Deploy Neo4j container
|
||||
5. Implement REST API with FastAPI
|
||||
6. Build MCP server
|
||||
7. Create Mintlify documentation site
|
||||
8. Testing and validation
|
||||
9. Push to git repository
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-10-13
|
||||
**Status**: Architecture Design Complete
|
||||
**Next Phase**: Implementation
|
||||
Reference in New Issue
Block a user