# 🏗️ Arquitectura del Sistema
Diseño técnico completo del sistema de memoria auto-evolutivo.
---
## 📋 Contenidos
1. [Visión General](#visión-general)
2. [Arquitectura de 3 Capas](#arquitectura-de-3-capas)
3. [Flujo de Datos](#flujo-de-datos)
4. [Componentes Principales](#componentes-principales)
5. [Sistema de Entidades y Relaciones](#sistema-de-entidades-y-relaciones)
6. [Decisiones de Diseño](#decisiones-de-diseño)
---
## Visión General
### Principios Arquitectónicos
**SOLID Principles:**
- ✅ **Single Responsibility:** Cada componente tiene una responsabilidad clara
- ✅ **Open/Closed:** Extensible mediante agentes y plugins sin modificar core
- ✅ **Liskov Substitution:** VectorStore puede intercambiarse por otras implementaciones
- ✅ **Interface Segregation:** Interfaces pequeñas y específicas
- ✅ **Dependency Inversion:** KnowledgeStore depende de abstracción, no implementación
**Otros Principios:**
- 🔄 **Separation of Concerns:** API, lógica, persistencia separadas
- 📦 **Modular Design:** Componentes independientes y reutilizables
- 🎯 **Single Source of Truth:** LanceDB es la única fuente de datos
- 🔌 **Plugin Architecture:** Agentes como plugins auto-contenidos
---
## Arquitectura de 3 Capas
```
┌──────────────────────────────────────────────────────────────────┐
│ CAPA 1: INTERFACES │
│ ┌─────────────┐ ┌─────────────┐ ┌──────────────────────┐ │
│ │ MCP Tools │ │ Slash │ │ CLI (terminal) │ │
│ │ (Claude) │ │ Commands │ │ memory-cli stats │ │
│ └──────┬──────┘ └──────┬──────┘ └──────────┬───────────┘ │
│ │ │ │ │
└─────────┼────────────────┼─────────────────────┼─────────────────┘
│ │ │
└────────────────┴─────────────────────┘
▼
┌──────────────────────────────────────────────────────────────────┐
│ CAPA 2: LÓGICA DE NEGOCIO │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ MCP Server (index.js) │ │
│ │ • Transport Layer (StdioServerTransport) │ │
│ │ • Tool Registration & Routing │ │
│ │ • Request Validation (Zod schemas) │ │
│ │ • Error Handling │ │
│ └──────────────────┬───────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────▼───────────────────────────────────────┐ │
│ │ KnowledgeStore (class) │ │
│ │ • Entity Management (CRUD) │ │
│ │ • Relation Management │ │
│ │ • Confidence System │ │
│ │ • Search & Retrieval │ │
│ │ • Stats & Analytics │ │
│ │ • Export Functionality │ │
│ └──────────────────┬───────────────────────────────────────┘ │
└───────────────────────┼──────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ CAPA 3: PERSISTENCIA │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ VectorStore (vector-store.js) │ │
│ │ • Embedding Generation (Transformers.js) │ │
│ │ • Vector Operations (add, search, update, delete) │ │
│ │ • LanceDB Abstraction │ │
│ │ • Schema Management │ │
│ └──────────────────┬───────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────▼───────────────────────────────────────┐ │
│ │ LanceDB Storage │ │
│ │ • Vector Database (.claude-memory/vectors/lancedb/) │ │
│ │ • Persistent Storage │ │
│ │ • Efficient Vector Search │ │
│ └───────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
```
---
## Flujo de Datos
### 1. User Request → Knowledge Capture
```
┌──────────┐
│ Usuario │ "Guarda decisión: Usar PostgreSQL"
└────┬─────┘
│
▼
┌─────────────────┐
│ MCP Tool Call │ save_knowledge({type: "decision", content: "..."})
└────┬────────────┘
│
▼
┌────────────────────┐
│ Input Validation │ Zod schema validation
└────┬───────────────┘
│
▼
┌──────────────────────┐
│ KnowledgeStore │ addEntry({...})
│ • Generate UUID │
│ • Set metadata │
│ • Prepare for store │
└────┬─────────────────┘
│
▼
┌──────────────────────┐
│ VectorStore │ add({...})
│ • Generate embedding│ Transformers.js (384D vector)
│ • Serialize arrays │ tags → JSON string
│ • Insert to LanceDB │
└────┬─────────────────┘
│
▼
┌──────────────────────┐
│ LanceDB │ Persistent storage
│ • Write to disk │
│ • Index vector │
└──────────────────────┘
```
### 2. Knowledge Search
```
┌──────────┐
│ Usuario │ "Busca decisiones sobre database"
└────┬─────┘
│
▼
┌─────────────────┐
│ MCP Tool Call │ search_knowledge({query: "database"})
└────┬────────────┘
│
▼
┌──────────────────────┐
│ KnowledgeStore │ search("database", {type: "decision"})
└────┬─────────────────┘
│
▼
┌──────────────────────┐
│ VectorStore │ search("database", limit: 10)
│ • Generate embedding│ Query → 384D vector
│ • Vector search │ Cosine similarity
│ • Filter results │ By type, confidence
└────┬─────────────────┘
│
▼
┌──────────────────────┐
│ LanceDB │ Vector similarity search
│ • ANN search │ Approximate Nearest Neighbors
│ • Return top K │
└────┬─────────────────┘
│
▼
┌──────────────────────┐
│ Post-Processing │
│ • Deserialize arrays│ JSON string → array
│ • Update metadata │ accessCount++, lastAccessed
│ • Format response │
└────┬─────────────────┘
│
▼
┌──────────┐
│ Results │ [{id, type, content, confidence, ...}, ...]
└──────────┘
```
### 3. Agent Workflow
```
┌──────────┐
│ Trigger │ Error occurs, task starts, etc.
└────┬─────┘
│
▼
┌─────────────────┐
│ Claude detects │ Matches trigger condition in CLAUDE.md
│ trigger │
└────┬────────────┘
│
▼
┌─────────────────┐
│ Task tool call │ Launch agent (subagent_type: "general-purpose")
└────┬────────────┘
│
▼
┌──────────────────────┐
│ Agent executes │
│ 1. Search memory │ mcp__memory__search_nodes
│ 2. Analyze findings │
│ 3. Create entities │ mcp__memory__create_entities
│ 4. Create relations │ mcp__memory__create_relations
└────┬─────────────────┘
│
▼
┌──────────────────────┐
│ Knowledge stored │ Entities + Relations in LanceDB
└────┬─────────────────┘
│
▼
┌──────────┐
│ Report │ Brief confirmation to Claude
└──────────┘
```
---
## Componentes Principales
### 1. MCP Server (`index.js`)
**Responsabilidad:** API Layer y Transport
**Componentes:**
```javascript
// Server initialization
const server = new Server({
name: 'self-improving-memory',
version: '2.0.0'
}, {
capabilities: {
tools: {} // Expose MCP tools
}
});
// Transport (stdio para Claude Desktop)
const transport = new StdioServerTransport();
// Tool registration
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{ name: 'create_entities', ... },
{ name: 'search_nodes', ... },
...
]
}));
// Tool execution
server.setRequestHandler(CallToolRequestSchema, async (request) => {
// Route to KnowledgeStore
});
```
**Herramientas Expuestas:**
1. `create_entities` - Crear entidades
2. `create_relations` - Crear relaciones
3. `add_observations` - Agregar observaciones
4. `search_nodes` - Buscar conocimiento
5. `open_nodes` - Abrir entidades específicas
6. `read_graph` - Leer grafo completo
7. `delete_entities` - Eliminar entidades
8. `delete_observations` - Eliminar observaciones
**Patterns Utilizados:**
- **Factory Pattern:** Para crear entidades
- **Strategy Pattern:** Routing de tools
- **Facade Pattern:** Simplifica acceso a KnowledgeStore
---
### 2. KnowledgeStore (clase en `index.js`)
**Responsabilidad:** Business Logic
**Métodos Principales:**
```javascript
class KnowledgeStore {
constructor(projectPath) {
this.vectorStore = new VectorStore(projectPath);
}
// Entity Management
async addEntry({ type, content, context, confidence, ... }) {
const id = crypto.randomUUID();
const entry = {
id,
type,
content,
context,
confidence,
verified: false,
tags: [],
timestamp: new Date().toISOString(),
accessCount: 0,
lastAccessed: null,
relatedIds: []
};
await this.vectorStore.add(entry);
return id;
}
// Search with filters
async search(query, { type, minConfidence, limit } = {}) {
const results = await this.vectorStore.search(query, limit);
// Filter by type
if (type) {
results = results.filter(r => r.type === type);
}
// Filter by confidence
if (minConfidence) {
results = results.filter(r => r.confidence >= minConfidence);
}
// Update access metadata
for (const result of results) {
await this.updateMetadata(result.id, {
accessCount: result.accessCount + 1,
lastAccessed: new Date().toISOString()
});
}
return results;
}
// Relation Management
async linkEntries(fromId, toId, relationType) {
const from = await this.getById(fromId);
if (!from.relatedIds.includes(toId)) {
from.relatedIds.push(toId);
await this.updateEntry(fromId, { relatedIds: from.relatedIds });
}
}
// Analytics
async getStats() {
const allEntries = await this.vectorStore.getAll();
return {
totalEntries: allEntries.length,
byType: this.groupBy(allEntries, 'type'),
byConfidence: this.groupByConfidence(allEntries),
verified: allEntries.filter(e => e.verified).length,
mostAccessedId: this.findMostAccessed(allEntries)?.id
};
}
// Export
async exportMarkdown() {
const entries = await this.vectorStore.getAll();
const grouped = this.groupBy(entries, 'type');
let md = '# Knowledge Base Export\n\n';
for (const [type, items] of Object.entries(grouped)) {
md += `## ${type}\n\n`;
for (const item of items) {
md += `### ${item.content}\n`;
md += `- Confidence: ${item.confidence}\n`;
md += `- Tags: ${item.tags.join(', ')}\n\n`;
}
}
return md;
}
}
```
**Patterns Utilizados:**
- **Repository Pattern:** Abstrae acceso a datos
- **Builder Pattern:** Construcción de queries complejas
- **Template Method:** Export en diferentes formatos
---
### 3. VectorStore (`vector-store.js`)
**Responsabilidad:** Vector Operations & LanceDB Abstraction
**Componentes:**
```javascript
class VectorStore {
constructor(projectPath) {
this.dbPath = path.join(projectPath, '.claude-memory', 'vectors', 'lancedb');
this.db = null;
this.table = null;
this.model = null; // Transformers.js model
}
// Initialization
async initialize() {
this.db = await lancedb.connect(this.dbPath);
// Check if table exists
const tableNames = await this.db.tableNames();
if (tableNames.includes('knowledge')) {
this.table = await this.db.openTable('knowledge');
} else {
// Create table with schema
this.table = await this.db.createTable('knowledge', SCHEMA);
}
// Warm-up embeddings model in background
this.warmupModel();
}
// Embedding generation
async generateEmbedding(text) {
if (!this.model) {
const { pipeline } = await import('@xenova/transformers');
this.model = await pipeline(
'feature-extraction',
'Xenova/all-MiniLM-L6-v2'
);
}
const output = await this.model(text, {
pooling: 'mean',
normalize: true
});
return Array.from(output.data); // 384D vector
}
// Add entry
async add(entry) {
const embedding = await this.generateEmbedding(
`${entry.type} ${entry.content} ${entry.context || ''}`
);
const record = {
id: entry.id,
vector: embedding,
text: entry.content,
type: entry.type,
content: entry.content,
context: entry.context || '',
confidence: entry.confidence,
verified: entry.verified,
tags: JSON.stringify(entry.tags), // Serialize
timestamp: entry.timestamp,
accessCount: entry.accessCount,
lastAccessed: entry.lastAccessed || '',
relatedIds: JSON.stringify(entry.relatedIds), // Serialize
indexed_at: new Date().toISOString()
};
await this.table.add([record]);
}
// Vector search
async search(query, limit = 10) {
const queryEmbedding = await this.generateEmbedding(query);
const results = await this.table
.search(queryEmbedding)
.limit(limit)
.execute();
// Deserialize arrays
return results.map(r => ({
...r,
tags: JSON.parse(r.tags || '[]'),
relatedIds: JSON.parse(r.relatedIds || '[]')
}));
}
// Update (delete + add pattern)
async update(id, updates) {
const existing = await this.getById(id);
const merged = { ...existing, ...updates };
await this.delete(id);
await this.add(merged);
}
// Metadata-only update (no re-embed)
async updateMetadata(id, metadata) {
// Direct SQL update for efficiency (no vector change)
const sql = `UPDATE knowledge SET ${Object.keys(metadata).map(k => `${k} = ?`).join(', ')} WHERE id = ?`;
await this.table.execute(sql, [...Object.values(metadata), id]);
}
}
```
**Patterns Utilizados:**
- **Singleton Pattern:** Model instance reutilizada
- **Lazy Loading:** Model se carga en primer uso
- **Adapter Pattern:** Abstrae LanceDB specifics
---
### 4. CLI Tool (`memory-cli.js`)
**Responsabilidad:** Terminal Interface
**Comandos:**
```javascript
const commands = {
init: async () => {
// Initialize .claude-memory directory
},
stats: async () => {
const store = new VectorStore(process.cwd());
const stats = await store.getStats();
console.log(formatStats(stats));
},
list: async (type) => {
const entries = await store.getAll();
const filtered = type ? entries.filter(e => e.type === type) : entries;
console.table(filtered.map(formatEntry));
},
search: async (query) => {
const results = await store.search(query);
console.log(formatResults(results));
},
show: async (id) => {
const entry = await store.getById(id);
console.log(formatDetail(entry));
},
export: async (format = 'md') => {
if (format === 'md') {
const md = await store.exportMarkdown();
fs.writeFileSync('knowledge-export.md', md);
}
},
analyze: async () => {
// Quality analysis
const entries = await store.getAll();
const lowConfidence = entries.filter(e => e.confidence < 0.5);
const unverified = entries.filter(e => !e.verified);
const unused = entries.filter(e => e.accessCount === 0);
console.log(`Low confidence: ${lowConfidence.length}`);
console.log(`Unverified: ${unverified.length}`);
console.log(`Unused: ${unused.length}`);
}
};
```
**Features:**
- Acceso directo a VectorStore (no usa MCP)
- Formateo con colores ANSI
- Instalable globalmente (`npm link`)
---
## Sistema de Entidades y Relaciones
### Entity Schema
```typescript
interface Entity {
// Identity
id: string; // UUID v4
name: string; // Human-readable name
entityType: string; // Tipo de entidad (17 tipos)
// Content
observations: string[]; // Array de observaciones
// Metadata (implicit)
confidence?: number; // 0-1 (stored in observations)
tags?: string[]; // (stored in observations)
timestamp?: string; // ISO8601
verified?: boolean; // (stored in observations)
}
```
### Relation Schema
```typescript
interface Relation {
from: string; // Entity name (source)
to: string; // Entity name (target)
relationType: string; // Tipo de relación
}
```
### Entity Types (17 tipos)
**Categoría: Proyecto & Código**
- `project` - Información del proyecto
- `component` - Componente/módulo de código
- `dependency` - Librería/herramienta externa
**Categoría: Aprendizaje**
- `error` - Error encontrado
- `solution` - Solución exitosa
- `pattern` - Patrón reutilizable
- `insight` - Aprendizaje importante
- `decision` - Decisión técnica
**Categoría: Usuario**
- `user-intent` - Qué quiere lograr el usuario
- `user-preference` - Preferencias del usuario
- `requirement` - Requisito o constraint
**Categoría: Estilo**
- `style-rule` - Regla de estilo de código
- `architectural-pattern` - Patrón arquitectónico
- `tool-preference` - Herramienta/library preferida
**Categoría: Sesiones**
- `session-snapshot` - Estado completo de sesión
- `continuation-point` - Punto de continuación
- `work-in-progress` - Trabajo incompleto
### Relation Types (ejemplos)
```
uses, depends on, fixes, implements, supersedes,
applies to, guided by, causes, prevents, enhances,
similar to, contradicts, requires, validates, extends
```
### Knowledge Graph Structure
```
┌──────────────┐
│ PROJECT │
│ my-web-app │
└───────┬──────┘
│ uses
┌─────────────┼─────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│COMPONENT │ │COMPONENT │ │DEPENDENCY│
│ Auth │ │ API │ │PostgreSQL│
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
│ implements │ applies to │ used in
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ DECISION │ │ ERROR │ │DECISION │
│ Use JWT │ │ CORS fail│ │ Use PG │
└────┬─────┘ └────┬─────┘ └──────────┘
│ │ fixed by
│ guided by ▼
▼ ┌──────────┐
┌──────────┐ │ SOLUTION │
│USER-PREF │ │Enable │
│Secure │ │CORS │
└──────────┘ └──────────┘
```
---
## Decisiones de Diseño
### 1. ¿Por qué LanceDB?
**Alternativas consideradas:**
- Pinecone (cloud-only, caro)
- Weaviate (overhead alto)
- ChromaDB (más lento)
- JSON + manual search (no escala)
**Razones para LanceDB:**
- ✅ Persistencia local (no depende de cloud)
- ✅ Vector search nativo y rápido
- ✅ Bajo overhead (embedded database)
- ✅ Escalable (hasta millones de vectores)
- ✅ Integración fácil con Node.js
### 2. ¿Por qué Transformers.js?
**Alternativas:**
- OpenAI Embeddings API (requiere API key, costo)
- Python sentence-transformers (requiere Python)
- Manual TF-IDF (menos semántico)
**Razones para Transformers.js:**
- ✅ 100% JavaScript (no Python dependency)
- ✅ Funciona offline (modelo local)
- ✅ Gratis y open-source
- ✅ Modelo pequeño pero efectivo (90MB)
- ✅ Rápido después de warm-up
### 3. ¿Por qué Modelo all-MiniLM-L6-v2?
**Specs:**
- Tamaño: ~90MB
- Dimensiones: 384
- Performance: 0.68 semantic similarity (benchmark)
**Trade-offs:**
- ✅ Pequeño y rápido
- ✅ Buena precisión para mayoría de casos
- ❌ No tan preciso como modelos grandes (768D)
**Conclusión:** Sweet spot entre tamaño/velocidad/precisión.
### 4. ¿Por qué 3 Capas?
**Separation of Concerns:**
- **Layer 1 (Interfaces):** Múltiples formas de interactuar
- **Layer 2 (Logic):** Business rules independientes de storage
- **Layer 3 (Persistence):** Fácil cambiar implementación
**Benefits:**
- Testeable (mock layers independientemente)
- Mantenible (cambios localizados)
- Extensible (agregar interfaces fácilmente)
### 5. ¿Por qué MCP Protocol?
**Alternativas:**
- REST API (overhead de servidor)
- GraphQL (complejidad innecesaria)
- Direct function calls (no portable)
**Razones para MCP:**
- ✅ Standard de Anthropic para Claude integrations
- ✅ Stdio transport (simple, sin networking)
- ✅ Schema validation built-in
- ✅ Auto-discovery de tools
### 6. ¿Por qué No JSON Storage?
**Problemas con JSON:**
- ❌ No search semántica (solo text match)
- ❌ O(n) para búsquedas
- ❌ No escala bien (>10k entries)
- ❌ Require cargar todo en memoria
**Benefits de Vector DB:**
- ✅ O(log n) búsqueda con ANN
- ✅ Semantic search (encuentra conceptos similares)
- ✅ Escalable sin límite práctico
- ✅ Lazy loading (no todo en RAM)
---
## Performance Considerations
### Latency Breakdown
```
Total search time: ~300-500ms
1. Query embedding generation: ~100-200ms (primera vez)
~10-20ms (warm model)
2. Vector search (LanceDB): ~50-100ms (10k entries)
~200-300ms (100k entries)
3. Post-processing: ~10-20ms
4. Metadata update: ~20-50ms
```
### Memory Usage
```
Base: ~50MB (Node.js runtime)
Transformers.js: ~90MB (model in memory)
LanceDB: ~20MB + (vectors * 384 * 4 bytes)
Example for 10k entries:
10,000 * 384 * 4 = ~15MB
Total: ~175MB (10k entries)
~265MB (100k entries)
```
### Scalability Targets
| Entries | DB Size | Search Latency | Memory |
|---------|---------|----------------|---------|
| 1k | ~5MB | <100ms | ~165MB |
| 10k | ~50MB | <200ms | ~175MB |
| 100k | ~500MB | <500ms | ~265MB |
| 1M | ~5GB | <1s | ~500MB |
---
## Security Considerations
### Data Privacy
- ✅ **Local-first:** Todo almacenado localmente
- ✅ **No cloud:** No envía datos a servicios externos
- ✅ **No tracking:** No telemetría
- ✅ **User control:** Usuario controla sus datos
### Input Validation
```javascript
// Zod schemas para validación
const EntitySchema = z.object({
name: z.string().min(1).max(200),
entityType: z.enum([...17 entity types]),
observations: z.array(z.string()).min(1)
});
// Sanitización
function sanitize(input) {
return input
.trim()
.replace(/[<>]/g, '') // Remove HTML tags
.slice(0, 10000); // Limit length
}
```
### Error Handling
```javascript
try {
await vectorStore.add(entity);
} catch (error) {
logger.error('Failed to add entity', {
error: error.message,
stack: error.stack,
entity: sanitizeForLog(entity)
});
throw new MCPError('Entity creation failed');
}
```
---
**Documentación relacionada:**
- [Agentes](AGENTS.md)
- [API Reference](API.md)
- [ROADMAP](../ROADMAP.md)