46faa78237
- Complete fact-based memory API with mem0-inspired approach - Individual fact extraction and deduplication - ADD/UPDATE/DELETE memory actions - Precision search with 0.86+ similarity scores - MCP server for Claude Code integration - Neo4j graph relationships and PostgreSQL vector storage - Comprehensive documentation with architecture and API docs - Matrix communication integration - Production-ready Docker setup with Ollama and Supabase 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
462 lines
18 KiB
HTML
462 lines
18 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>Architecture - LangMem Documentation</title>
|
|
<meta name="description" content="Detailed architecture documentation for LangMem showing system components, data flow, and integration patterns.">
|
|
<link rel="stylesheet" href="../assets/css/style.css">
|
|
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
|
|
</head>
|
|
<body>
|
|
<header>
|
|
<nav>
|
|
<a href="../" class="logo">🧠 LangMem</a>
|
|
<ul class="nav-links">
|
|
<li><a href="../">Home</a></li>
|
|
<li><a href="../architecture/">Architecture</a></li>
|
|
<li><a href="../implementation/">Implementation</a></li>
|
|
<li><a href="../api/">API Docs</a></li>
|
|
</ul>
|
|
</nav>
|
|
</header>
|
|
|
|
<main>
|
|
<section class="hero">
|
|
<h1>System Architecture</h1>
|
|
<p>Comprehensive overview of the LangMem system architecture, components, and data flow patterns.</p>
|
|
</section>
|
|
|
|
<section class="mb-4">
|
|
<h2>System Overview</h2>
|
|
<div class="diagram-container">
|
|
<div class="diagram-title">High-Level Architecture</div>
|
|
<div class="mermaid">
|
|
graph TB
|
|
subgraph "Client Applications"
|
|
A[n8n Workflows]
|
|
B[Claude Code CLI]
|
|
C[Custom Applications]
|
|
end
|
|
|
|
subgraph "API Gateway Layer"
|
|
D[Memory Service API]
|
|
E[Authentication Layer]
|
|
F[Rate Limiting]
|
|
end
|
|
|
|
subgraph "Core Processing Layer"
|
|
G[LangMem SDK]
|
|
H[Memory Manager]
|
|
I[Context Assembler]
|
|
J[Hybrid Retrieval Engine]
|
|
end
|
|
|
|
subgraph "Model Layer"
|
|
K[Ollama Local LLM]
|
|
L[Embedding Generator]
|
|
M[Entity Extractor]
|
|
end
|
|
|
|
subgraph "Storage Layer"
|
|
N[Supabase PostgreSQL]
|
|
O[pgvector Extension]
|
|
P[Neo4j Graph DB]
|
|
Q[Vector Indexes]
|
|
end
|
|
|
|
subgraph "Infrastructure"
|
|
R[Docker Network]
|
|
S[Container Orchestration]
|
|
T[Health Monitoring]
|
|
end
|
|
|
|
A --> D
|
|
B --> D
|
|
C --> D
|
|
D --> E
|
|
D --> F
|
|
D --> G
|
|
G --> H
|
|
G --> I
|
|
G --> J
|
|
J --> K
|
|
J --> L
|
|
J --> M
|
|
H --> N
|
|
H --> P
|
|
N --> O
|
|
N --> Q
|
|
|
|
R --> S
|
|
S --> T
|
|
|
|
style G fill:#2563eb,stroke:#1e40af,stroke-width:3px,color:#fff
|
|
style N fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff
|
|
style P fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#fff
|
|
style K fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#fff
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="mb-4">
|
|
<h2>Data Flow Architecture</h2>
|
|
<div class="diagram-container">
|
|
<div class="diagram-title">Data Ingestion Flow</div>
|
|
<div class="mermaid">
|
|
sequenceDiagram
|
|
participant Client
|
|
participant API as Memory Service API
|
|
participant LM as LangMem SDK
|
|
participant OL as Ollama
|
|
participant SB as Supabase
|
|
participant N4J as Neo4j
|
|
|
|
Client->>API: POST /v1/ingest
|
|
API->>LM: Process Document
|
|
LM->>LM: Text Chunking
|
|
LM->>OL: Generate Embeddings
|
|
OL-->>LM: Vector Embeddings
|
|
LM->>SB: Store Chunks + Embeddings
|
|
SB-->>LM: Chunk IDs
|
|
LM->>OL: Extract Entities
|
|
OL-->>LM: Entity List
|
|
LM->>N4J: Store Graph Data
|
|
N4J-->>LM: Graph Node IDs
|
|
LM->>N4J: Link to Chunk IDs
|
|
LM-->>API: Ingestion Complete
|
|
API-->>Client: Success Response
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="mb-4">
|
|
<div class="diagram-container">
|
|
<div class="diagram-title">Data Retrieval Flow</div>
|
|
<div class="mermaid">
|
|
sequenceDiagram
|
|
participant Client
|
|
participant API as Memory Service API
|
|
participant LM as LangMem SDK
|
|
participant OL as Ollama
|
|
participant SB as Supabase
|
|
participant N4J as Neo4j
|
|
|
|
Client->>API: POST /v1/context/retrieve
|
|
API->>LM: Query Processing
|
|
LM->>OL: Generate Query Embedding
|
|
OL-->>LM: Query Vector
|
|
LM->>SB: Vector Similarity Search
|
|
SB-->>LM: Relevant Chunks
|
|
LM->>LM: Extract Entities from Chunks
|
|
LM->>N4J: Graph Traversal Query
|
|
N4J-->>LM: Related Entities/Facts
|
|
LM->>LM: Context Assembly
|
|
LM->>LM: Ranking & Filtering
|
|
LM-->>API: Augmented Context
|
|
API-->>Client: Context Response
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="mb-4">
|
|
<h2>Component Details</h2>
|
|
<div class="grid grid-2">
|
|
<div class="card">
|
|
<h3>🧠 LangMem SDK</h3>
|
|
<p><strong>Purpose:</strong> Core memory orchestration layer</p>
|
|
<p><strong>Key Features:</strong></p>
|
|
<ul>
|
|
<li>Storage-agnostic memory API</li>
|
|
<li>Active memory tools</li>
|
|
<li>Background memory management</li>
|
|
<li>LangGraph integration</li>
|
|
</ul>
|
|
<p><strong>Integration:</strong> Coordinates between vector and graph storage</p>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h3>🐘 Supabase + pgvector</h3>
|
|
<p><strong>Purpose:</strong> Vector storage and semantic search</p>
|
|
<p><strong>Key Features:</strong></p>
|
|
<ul>
|
|
<li>1536-dimensional embeddings</li>
|
|
<li>HNSW indexing for performance</li>
|
|
<li>Unified data + vector storage</li>
|
|
<li>SQL query capabilities</li>
|
|
</ul>
|
|
<p><strong>Scale:</strong> Handles 1.6M+ embeddings efficiently</p>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h3>🔗 Neo4j Graph Database</h3>
|
|
<p><strong>Purpose:</strong> Relationship storage and graph queries</p>
|
|
<p><strong>Key Features:</strong></p>
|
|
<ul>
|
|
<li>Entity relationship modeling</li>
|
|
<li>Graph traversal capabilities</li>
|
|
<li>Community detection algorithms</li>
|
|
<li>Cypher query language</li>
|
|
</ul>
|
|
<p><strong>Integration:</strong> Links to Supabase via chunk IDs</p>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h3>🦙 Ollama Local LLM</h3>
|
|
<p><strong>Purpose:</strong> Local model inference and embeddings</p>
|
|
<p><strong>Key Features:</strong></p>
|
|
<ul>
|
|
<li>Privacy-first local processing</li>
|
|
<li>OpenAI-compatible API</li>
|
|
<li>Multiple model support</li>
|
|
<li>Efficient quantization</li>
|
|
</ul>
|
|
<p><strong>Models:</strong> Llama 3.3, DeepSeek-R1, Phi-4, Gemma 3</p>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="mb-4">
|
|
<h2>Docker Network Architecture</h2>
|
|
<div class="diagram-container">
|
|
<div class="diagram-title">Container Network Topology</div>
|
|
<div class="mermaid">
|
|
graph TB
|
|
subgraph "localai_network (Bridge)"
|
|
subgraph "Memory Stack"
|
|
A[memory_service:8000]
|
|
B[supabase:5432]
|
|
C[neo4j:7687]
|
|
D[ollama:11434]
|
|
end
|
|
|
|
subgraph "Existing Services"
|
|
E[n8n:5678]
|
|
F[Other Services]
|
|
end
|
|
end
|
|
|
|
subgraph "External Access"
|
|
G[Caddy Proxy]
|
|
H[docs.klas.chat]
|
|
end
|
|
|
|
A <--> B
|
|
A <--> C
|
|
A <--> D
|
|
A <--> E
|
|
|
|
G --> H
|
|
G --> A
|
|
|
|
style A fill:#2563eb,stroke:#1e40af,stroke-width:2px,color:#fff
|
|
style B fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff
|
|
style C fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#fff
|
|
style D fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#fff
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="mb-4">
|
|
<h2>Database Schema Design</h2>
|
|
<div class="grid grid-2">
|
|
<div class="card">
|
|
<h3>📊 Supabase Schema</h3>
|
|
<div class="code-block">
|
|
<pre><code>CREATE TABLE documents (
|
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
|
content TEXT NOT NULL,
|
|
embedding VECTOR(1536),
|
|
metadata JSONB,
|
|
source_url TEXT,
|
|
created_at TIMESTAMP DEFAULT NOW(),
|
|
updated_at TIMESTAMP DEFAULT NOW()
|
|
);
|
|
|
|
CREATE INDEX ON documents
|
|
USING ivfflat (embedding vector_cosine_ops)
|
|
WITH (lists = 100);
|
|
|
|
CREATE INDEX ON documents
|
|
USING gin (metadata);</code></pre>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h3>🔗 Neo4j Schema</h3>
|
|
<div class="code-block">
|
|
<pre><code>// Node Types
|
|
CREATE (doc:DocumentChunk {
|
|
id: $uuid,
|
|
supabase_id: $supabase_id,
|
|
title: $title,
|
|
created_at: datetime()
|
|
})
|
|
|
|
CREATE (person:Person {
|
|
name: $name,
|
|
type: "person"
|
|
})
|
|
|
|
CREATE (concept:Concept {
|
|
name: $name,
|
|
type: "concept"
|
|
})
|
|
|
|
// Relationships
|
|
CREATE (doc)-[:MENTIONS]->(person)
|
|
CREATE (doc)-[:DISCUSSES]->(concept)
|
|
CREATE (person)-[:RELATED_TO]->(concept)</code></pre>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="mb-4">
|
|
<h2>Security Architecture</h2>
|
|
<div class="diagram-container">
|
|
<div class="diagram-title">Security Layers</div>
|
|
<div class="mermaid">
|
|
graph TB
|
|
subgraph "External Layer"
|
|
A[Caddy Proxy]
|
|
B[TLS Termination]
|
|
C[Rate Limiting]
|
|
end
|
|
|
|
subgraph "API Layer"
|
|
D[Authentication]
|
|
E[Authorization]
|
|
F[Input Validation]
|
|
end
|
|
|
|
subgraph "Application Layer"
|
|
G[MCP Resource Indicators]
|
|
H[API Key Management]
|
|
I[Session Management]
|
|
end
|
|
|
|
subgraph "Network Layer"
|
|
J[Docker Network Isolation]
|
|
K[Container Security]
|
|
L[Port Restrictions]
|
|
end
|
|
|
|
subgraph "Data Layer"
|
|
M[Database Authentication]
|
|
N[Encryption at Rest]
|
|
O[Backup Security]
|
|
end
|
|
|
|
A --> D
|
|
B --> D
|
|
C --> D
|
|
D --> G
|
|
E --> G
|
|
F --> G
|
|
G --> J
|
|
H --> J
|
|
I --> J
|
|
J --> M
|
|
K --> M
|
|
L --> M
|
|
|
|
style A fill:#ef4444,stroke:#dc2626,stroke-width:2px,color:#fff
|
|
style D fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#fff
|
|
style G fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff
|
|
style J fill:#2563eb,stroke:#1e40af,stroke-width:2px,color:#fff
|
|
style M fill:#8b5cf6,stroke:#7c3aed,stroke-width:2px,color:#fff
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="mb-4">
|
|
<h2>Performance Considerations</h2>
|
|
<div class="grid grid-3">
|
|
<div class="card">
|
|
<h3>⚡ Vector Search</h3>
|
|
<ul>
|
|
<li>HNSW indexing for sub-second search</li>
|
|
<li>Dimension optimization (1536)</li>
|
|
<li>Batch processing for bulk operations</li>
|
|
<li>Query result caching</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h3>🔍 Graph Queries</h3>
|
|
<ul>
|
|
<li>Property and relationship indexing</li>
|
|
<li>Cypher query optimization</li>
|
|
<li>Limited traversal depth</li>
|
|
<li>Result set pagination</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="card">
|
|
<h3>🦙 Model Inference</h3>
|
|
<ul>
|
|
<li>Model quantization strategies</li>
|
|
<li>Embedding batch processing</li>
|
|
<li>Local GPU acceleration</li>
|
|
<li>Response caching</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="mb-4">
|
|
<h2>Scalability Patterns</h2>
|
|
<div class="diagram-container">
|
|
<div class="diagram-title">Scaling Strategy</div>
|
|
<div class="mermaid">
|
|
graph LR
|
|
subgraph "Current (Local)"
|
|
A[Single Node] --> B[Docker Compose]
|
|
B --> C[Local Resources]
|
|
end
|
|
|
|
subgraph "Stage 1 (Optimized)"
|
|
D[Resource Limits] --> E[Connection Pooling]
|
|
E --> F[Query Optimization]
|
|
end
|
|
|
|
subgraph "Stage 2 (Distributed)"
|
|
G[Load Balancer] --> H[Multiple API Instances]
|
|
H --> I[Shared Storage]
|
|
end
|
|
|
|
subgraph "Stage 3 (Cloud)"
|
|
J[Managed Services] --> K[Auto Scaling]
|
|
K --> L[Multi-Region]
|
|
end
|
|
|
|
C --> D
|
|
F --> G
|
|
I --> J
|
|
|
|
style A fill:#ef4444,stroke:#dc2626,stroke-width:2px,color:#fff
|
|
style D fill:#f59e0b,stroke:#d97706,stroke-width:2px,color:#fff
|
|
style G fill:#22c55e,stroke:#16a34a,stroke-width:2px,color:#fff
|
|
style J fill:#2563eb,stroke:#1e40af,stroke-width:2px,color:#fff
|
|
</div>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="text-center">
|
|
<h2>Next Steps</h2>
|
|
<p class="mb-3">Ready to implement this architecture? Follow our detailed implementation guide.</p>
|
|
<div class="cta-buttons">
|
|
<a href="../implementation/" class="btn btn-primary">📚 Implementation Guide</a>
|
|
<a href="../api/" class="btn btn-secondary">📡 API Documentation</a>
|
|
</div>
|
|
</section>
|
|
</main>
|
|
|
|
<footer style="text-align: center; padding: 2rem; margin-top: 4rem; color: var(--text-secondary);">
|
|
<p>© 2025 LangMem Documentation. Built with modern web technologies.</p>
|
|
</footer>
|
|
|
|
<script src="../assets/js/main.js"></script>
|
|
</body>
|
|
</html> |