@slorenzot/memento-mcp-server 2.0.9 → 2.1.1

package/README.es.md

@@ -5,443 +5,441 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)
 [![MCP](https://img.shields.io/badge/MCP-Protocol-green.svg)](https://modelcontextprotocol.io)
 
-> Model Context Protocol (MCP) server providing 15 memory tools for AI agent integration with Claude Desktop, VS Code, and other MCP clients.
+> Servidor Model Context Protocol (MCP) con 24 herramientas de memoria para integracion de agentes de IA con Claude Desktop, VS Code, OpenCode y otros clientes MCP.
 
-## 🚀 Instalación
+## Instalacion
 
 ```bash
-# Using Bun (recomendado)
+# Usando Bun (recomendado)
 bun add @slorenzot/memento-mcp-server
 
-# Using npm
+# Usando npm
 npm install @slorenzot/memento-mcp-server
 ```
 
-## 💡 Uso Básico
+## Uso Basico
 
-### TypeScript
-```typescript
-import { MCPServer } from '@slorenzot/memento-mcp-server';
+### Shell
 
-// Inicializar servidor MCP
-const server = new MCPServer('./data/memento.db');
-
-// Iniciar servidor (usa stdio para comunicación MCP)
-// Nota: Este servidor está diseñado para ser ejecutado por clientes MCP
-// No es necesario llamar start() manualmente en producción
-```
-
-### Shell/Bun
 ```bash
 # Ejecutar servidor MCP (recomendado)
-npx -p @slorenzot/memento-mcp-server
-
-# O usando bunx (si está instalado globalmente)
 bunx @slorenzot/memento-mcp-server
 
-# Usar con variable de entorno para base de datos personalizada
-MEMENTO_DB_PATH=/custom/path/database.db npx -p @slorenzot/memento-mcp-server
-```
-
-## 🔧 API Esencial
-
-### Clase Principal
-
-#### `MCPServer(dbPath?: string)`
-
-Constructor del servidor MCP con integración automática al motor de memoria.
-
-**Parámetros:**
-- `dbPath` (opcional): Ruta al archivo de base de datos. Default: `'./data/memento.db'`
-
-**Ejemplo:**
-```typescript
-const server = new MCPServer('./custom/path.db');
+# Usar con ruta personalizada de base de datos
+MEMENTO_DB_PATH=/ruta/personalizada/database.db bunx @slorenzot/memento-mcp-server
 ```
 
----
-
-#### Métodos de Control
-
-##### `start()`
-
-Inicia el servidor MCP y comienza a escuchar solicitudes MCP via stdio.
-
-**Retorna:** `Promise<void>`
-
-**Nota:** Este método es llamado automáticamente cuando el servidor se inicia como proceso independiente.
-
----
-
-##### `close()`
-
-Detiene el servidor MCP y cierra la conexión con la base de datos.
-
-**Retorna:** `void`
+### TypeScript
 
-**Ejemplo:**
 ```typescript
-const server = new MCPServer();
+import { MCPServer } from '@slorenzot/memento-mcp-server';
 
-// En cleanup o shutdown
-server.close();
+const server = new MCPServer('./data/memento.db');
+// El servidor usa stdio para comunicacion MCP
+// Disenado para ser ejecutado por clientes MCP
 ```
 
----
+## Herramientas MCP Disponibles
 
-## 🛠️ Herramientas MCP Disponibles
+El servidor proporciona 24 herramientas MCP organizadas por categoria:
 
-El servidor proporciona 15 herramientas MCP para gestión de memoria:
-
-### Gestión de Observaciones
+### Core — Observaciones
 
 #### `mem_save`
-Guarda una nueva observación en la memoria.
 
-**Parámetros:**
+Guarda una observacion en memoria persistente. Llama PROACTIVAMENTE despues de tomar decisiones, corregir bugs o descubrir algo no obvio.
+
+**Parametros:**
 ```typescript
 {
-  title: string;
-  content: string;
-  type?: 'decision' | 'bug' | 'discovery' | 'note';
-  topic_key?: string;
-  project_id?: string;
+  title: string;                    // Titulo corto y buscable
+  content: string;                  // Estructurado: Que/Porque/Donde/Aprendido
+  type?: 'decision' | 'bug' | 'discovery' | 'note' | 'summary' |
+         'learning' | 'pattern' | 'architecture' | 'config' | 'preference';
+  topic_key?: string;               // Clave estable para agrupar (ej. "architecture/auth")
+  project_id?: string;              // Identificador del proyecto
   metadata?: Record<string, unknown>;
+  scope?: 'project' | 'personal';   // Alcance (por defecto: project)
+  pinned?: boolean;                  // Fijar para inyeccion en system prompt
+  read_only?: boolean;               // Marcar como solo lectura
 }
 ```
 
-**Ejemplo de uso:**
-```typescript
-await mem_save({
-  title: 'Decisión de arquitectura',
-  content: 'Usar PostgreSQL en lugar de MySQL',
-  type: 'decision',
-  project_id: 'my-project'
-});
-```
-
----
-
 #### `mem_search`
-Busca observaciones usando búsqueda full-text.
 
-**Parámetros:**
+Busca observaciones usando busqueda full-text (FTS5). Los resultados estan TRUNCADOS — usa `mem_get_observation` para contenido completo.
+
+**Parametros:**
 ```typescript
 {
   query?: string;
-  type?: 'decision' | 'bug' | 'discovery' | 'note';
+  type?: /* 10 tipos de observacion */;
   project_id?: string;
   topic_key?: string;
-  limit?: number;
+  limit?: number;                    // Por defecto: 10
   offset?: number;
+  include_deleted?: boolean;
+  scope?: 'project' | 'personal';
+  sort?: 'relevance' | 'chronological';  // Por defecto: relevance
+  mode?: 'keyword' | 'semantic' | 'hybrid';  // Por defecto: keyword
 }
 ```
 
----
-
 #### `mem_get_observation`
-Obtiene una observación específica por ID.
 
-**Parámetros:**
+Obtiene el contenido completo de una observacion especifica por ID.
+
+**Parametros:**
 ```typescript
 {
   id: number;
+  include_deleted?: boolean;
 }
 ```
 
----
-
 #### `mem_update`
-Actualiza una observación existente.
 
-**Parámetros:**
+Actualiza una observacion existente. Solo los campos proporcionados seran actualizados.
+
+**Parametros:**
 ```typescript
 {
   id: number;
   title?: string;
   content?: string;
-  type?: 'decision' | 'bug' | 'discovery' | 'note';
+  type?: /* 10 tipos de observacion */;
   topic_key?: string;
-  metadata?: Record<string, unknown>;
+  pinned?: boolean;
 }
 ```
 
----
+#### `mem_replace`
 
-#### `mem_delete`
-Elimina una observación por ID.
+Reemplaza un substring dentro de una observacion. Mas eficiente en tokens que `mem_update` para cambios pequenos. Respeta la proteccion de solo lectura.
 
-**Parámetros:**
+**Parametros:**
 ```typescript
 {
   id: number;
+  old_text: string;    // Debe ser unico en el contenido
+  new_text: string;
 }
 ```
 
----
+### Ciclo de Vida
 
-### Gestión de Sesiones
+#### `mem_delete`
 
-#### `mem_session_start`
-Inicia una nueva sesión para seguimiento de conversaciones.
+Gestion consolidada del ciclo de vida de observaciones.
 
-**Parámetros:**
+**Parametros:**
 ```typescript
 {
-  project_id: string;
-  metadata?: Record<string, unknown>;
+  id?: number;                                           // Requerido para soft/restore
+  action?: 'soft' | 'permanent' | 'restore' | 'list';   // Por defecto: soft
+  reason?: string;                                        // Para accion soft
+  confirm?: boolean;                                      // Requerido para permanent
+  project_id?: string;                                    // Para list/permanent
+  observation_ids?: number[];                              // IDs especificos a purgar
+  limit?: number;                                         // Para accion list
 }
 ```
 
----
+#### `mem_merge`
 
-#### `mem_session_end`
-Finaliza una sesión activa.
+Fusiona observaciones relacionadas en un solo registro. SIEMPRE usar `dry_run: true` primero.
 
-**Parámetros:**
+**Parametros:**
 ```typescript
 {
-  id: number;
+  project_id: string;
+  topic_key?: string;
+  observation_ids?: number[];
+  strategy?: 'by_topic' | 'by_similarity' | 'by_ids';
+  dry_run?: boolean;
 }
 ```
 
----
+#### `mem_export`
 
-#### `mem_list_sessions`
-Lista todas las sesiones del proyecto.
+Exporta observaciones a JSON, XML o TXT.
 
-**Parámetros:**
+**Parametros:**
 ```typescript
 {
+  format?: 'json' | 'xml' | 'txt';
   project_id?: string;
-  limit?: number;
-  offset?: number;
+  type?: /* 10 tipos de observacion */;
+  topic_key?: string;
+  date_from?: string;
+  date_to?: string;
+  include_deleted?: boolean;
 }
 ```
 
----
+### Pin & Lock
 
-#### `mem_get_session`
-Obtiene una sesión específica.
+#### `mem_pin`
 
-**Parámetros:**
-```typescript
-{
-  id: number;
-}
-```
+Fija una observacion para inyeccion permanente en system prompt.
 
----
+**Parametros:** `{ id: number }`
 
-### Herramientas de Utilidad
+#### `mem_unpin`
+
+Elimina la observacion de la inyeccion en system prompt.
+
+**Parametros:** `{ id: number }`
+
+#### `mem_lock`
+
+Marca la observacion como solo lectura (previene modificaciones del agente).
+
+**Parametros:** `{ id: number }`
+
+#### `mem_unlock`
+
+Permite modificaciones en una observacion bloqueada.
+
+**Parametros:** `{ id: number }`
+
+### Gestion de Sesiones
+
+#### `mem_session_start`
 
-#### `mem_timeline`
-Obtiene una línea temporal de observaciones.
+Inicia una nueva sesion de memoria. Cierra automaticamente sesiones obsoletas del proyecto.
 
-**Parámetros:**
+**Parametros:**
 ```typescript
 {
   project_id?: string;
-  session_id?: number;
-  limit?: number;
-  offset?: number;
+  metadata?: Record<string, unknown>;
 }
 ```
 
----
+#### `mem_session_end`
 
-#### `mem_stats`
-Obtiene estadísticas del sistema de memoria.
+Finaliza la sesion activa. Llama ANTES de cerrar una conversacion.
 
-**Retorna:** Métricas de uso, totales por tipo, etc.
+**Parametros:** `{}`
 
----
+#### `mem_session_summary`
 
-#### `mem_import`
-Importa observaciones desde JSON.
+Guarda un resumen estructurado de sesion (Objetivo/Descubrimientos/Logros/Archivos). Usa esta herramienta NATIVA en lugar de `mem_save` con tipo "summary".
 
-**Parámetros:**
+**Parametros:**
 ```typescript
 {
-  data: Array<{
-    title: string;
-    content: string;
-    type?: string;
-    project_id?: string;
-  }>;
+  content: string;          // Estructurado: Objetivo/Descubrimientos/Logros/Archivos
+  project_id?: string;
+  session_id?: number;
 }
 ```
 
----
+#### `mem_context`
 
-#### `mem_export`
-Exporta observaciones a JSON.
+Recuperacion rapida de contexto. Retorna observaciones recientes ordenadas por created_at DESC. NO usa FTS5.
 
-**Parámetros:**
+**Parametros:**
 ```typescript
 {
   project_id?: string;
-  type?: string;
-  limit?: number;
+  limit?: number;           // Por defecto: 20
+  scope?: 'project' | 'personal';
 }
 ```
 
----
+### Captura
 
-### Herramientas de Sistema
+#### `mem_capture_passive`
 
-#### `mem_health`
-Verifica el estado del sistema de memoria.
+Analiza texto para extraer aprendizajes de secciones "## Key Learnings:" o "## Aprendizajes Clave:". Deduplica por similitud Jaccard.
 
-**Retorna:** Estado de conexión, salud de base de datos, etc.
+**Parametros:**
+```typescript
+{
+  content: string;
+  project_id?: string;
+  session_id?: number;
+  source?: string;
+}
+```
 
----
+### Diagnostico
 
-#### `mem_config`
-Obtiene la configuración actual del servidor.
+#### `mem_status`
 
-**Retorna:** Configuración de rutas, versión, etc.
+Herramienta de diagnostico compuesta. Reemplaza `mem_stats`, `mem_health`, `mem_config`, `mem_list_sessions`, `mem_get_session`.
 
----
+**Parametros:**
+```typescript
+{
+  section?: 'all' | 'health' | 'stats' | 'config' | 'sessions';
+  session_id?: number;       // Obtener detalles de sesion especifica
+  project_id?: string;       // Filtrar sesiones por proyecto
+  limit?: number;            // Maximo de sesiones (por defecto: 20)
+}
+```
 
-## ⚡ Ejemplos Prácticos
+### Journal — Audit Trail
 
-### Ejemplo 1: Integración con Claude Desktop
+#### `mem_journal_write`
 
-```json
+Crea una entrada de journal inmutable. Las entradas no pueden editarse ni eliminarse. Usa `supersedes` para corregir entradas anteriores.
+
+**Parametros:**
+```typescript
 {
-  "mcpServers": {
-    "memento": {
-      "command": "bun",
-      "args": ["run", "node_modules/@slorenzot/memento-mcp-server/dist/index.js"],
-      "env": {
-        "DATABASE_PATH": "./data/memento.db"
-      }
-    }
-  }
+  title: string;
+  body: string;
+  tags?: string[];
+  project_id?: string;
+  supersedes?: number;
+  metadata?: Record<string, unknown>;
 }
 ```
 
-### Ejemplo 2: Uso Programático del Servidor
+#### `mem_journal_read`
 
-```typescript
-import { MCPServer } from '@slorenzot/memento-mcp-server';
-
-// Crear servidor personalizado
-const server = new MCPServer('./memory.db');
+Lee una entrada de journal por ID.
 
-// El servidor manejará automáticamente solicitudes MCP
-// cuando sea ejecutado por un cliente MCP
+**Parametros:** `{ id: number }`
 
-// Para control manual (testing)
-const toolResult = await server.handleToolCall('mem_save', {
-  title: 'Test observación',
-  content: 'Contenido de prueba',
-  type: 'note',
-  project_id: 'test-project'
-});
+#### `mem_journal_search`
 
-console.log('Resultado:', toolResult);
+Busca entradas de journal con FTS5, tags y filtros de fecha.
 
-// Cerrar cuando termine
-server.close();
+**Parametros:**
+```typescript
+{
+  query?: string;
+  tags?: string[];
+  project_id?: string;
+  active_only?: boolean;     // Excluir entradas reemplazadas
+  date_from?: string;
+  date_to?: string;
+  limit?: number;
+  offset?: number;
+}
 ```
 
-### Ejemplo 3: Flujo Completo de Sesión
+### Sync — Nube
 
-```typescript
-// Usando herramientas MCP a través del servidor
+#### `mem_sync_status`
 
-// 1. Iniciar sesión
-const sessionStart = await mem_session_start({
-  project_id: 'my-app',
-  metadata: { agent: 'claude' }
-});
+Verifica el estado de autenticacion de sync y metadatos de la ultima sincronizacion.
 
-console.log('Sesión iniciada:', sessionStart.id);
+**Parametros:** `{}`
 
-// 2. Guardar observaciones durante trabajo
-await mem_save({
-  title: 'Configuración completada',
-  content: 'Servidor configurado en puerto 3000',
-  type: 'decision',
-  project_id: 'my-app'
-});
+#### `mem_sync_project`
+
+Sincronizacion bidireccional con memento-hub. Primera vez: retorna URL de verificacion y codigo de usuario.
 
-// 3. Buscar decisiones anteriores
-const searchResults = await mem_search({
-  query: 'configuración servidor',
-  type: 'decision'
-});
+**Parametros:**
+```typescript
+{
+  project_id: string;
+  device_code?: string;      // Reanudar auth despues de que el usuario autoriza
+}
+```
 
-console.log('Decisiones encontradas:', searchResults.observations);
+#### `mem_logout`
 
-// 4. Finalizar sesión
-await mem_session_end({ id: sessionStart.id });
+Limpia el token de sincronizacion. El agente necesitara re-autenticarse.
 
-// 5. Obtener estadísticas
-const stats = await mem_stats();
-console.log('Total observaciones:', stats.total);
-console.log('Por tipo:', stats.by_type);
-```
+**Parametros:** `{}`
 
-## 🔗 Integración con Clientes MCP
+## Integracion con Clientes MCP
 
 ### Claude Desktop
+
 ```json
 {
   "mcpServers": {
     "memento": {
-      "command": "bun",
-      "args": [
-        "run",
-        "node_modules/@slorenzot/memento-mcp-server/dist/index.js"
-      ],
+      "command": "bunx",
+      "args": ["@slorenzot/memento-mcp-server"],
       "env": {
-        "DATABASE_PATH": "${userHome}/.memento/database.db"
+        "MEMENTO_DB_PATH": "${userHome}/.memento/data/memento.db"
       }
     }
   }
 }
 ```
 
-### VS Code (con extensión MCP)
+### VS Code (con extension MCP)
+
 ```json
 {
   "mcp.servers": {
     "memento": {
-      "command": "bun",
-      "args": [
-        "run",
-        "node_modules/@slorenzot/memento-mcp-server/dist/index.js"
-      ]
+      "command": "bunx",
+      "args": ["@slorenzot/memento-mcp-server"]
+    }
+  }
+}
+```
+
+### OpenCode
+
+```json
+{
+  "mcpServers": {
+    "memento": {
+      "command": "bunx",
+      "args": ["@slorenzot/memento-mcp-server"]
     }
   }
 }
 ```
 
-## ⚠️ Licencia Restrictiva
+## Flujo Completo de Sesion
+
+```typescript
+// 1. Iniciar sesion
+await mem_session_start({ project_id: 'my-app' })
+
+// 2. Guardar observaciones durante el trabajo
+await mem_save({
+  title: 'Usar PostgreSQL para auth',
+  content: 'Que: Cambiar a PostgreSQL\nPorque: Mejor soporte JSON\nDonde: src/db/config.ts',
+  type: 'decision',
+  topic_key: 'architecture/database',
+  project_id: 'my-app'
+})
+
+// 3. Recuperacion rapida de contexto
+await mem_context({ project_id: 'my-app', limit: 10 })
+
+// 4. Busqueda con modo semantico
+await mem_search({
+  query: 'configuracion base de datos',
+  mode: 'semantic',
+  project_id: 'my-app'
+})
 
-Este paquete está bajo **Licencia CC BY-NC-ND 4.0**:
-- ✅ **Uso personal y educacional permitido**
-- ✅ **Compartir con atribución al autor**
-- ❌ **Uso comercial NO permitido**
-- ❌ **Modificaciones o forks NO permitidos**
+// 5. Guardar resumen de sesion (herramienta NATIVA)
+await mem_session_summary({
+  content: '## Objetivo\nConfigurar base de datos\n## Descubrimientos\nPostgreSQL tiene mejor soporte JSON\n## Logros\nConfigurada conexion PostgreSQL',
+  project_id: 'my-app'
+})
 
-**Autor**: Soulberto Lorenzo (slorenzot@gmail.com)
+// 6. Finalizar sesion
+await mem_session_end()
+```
 
-## 🔄 Dependencias
+## Dependencias
 
 ### Dependencias Principales
-- `@slorenzot/memento-core` - Motor de memoria
-- `@modelcontextprotocol/sdk` - SDK de Model Context Protocol
-- `zod` - Validación de esquemas
+- `@slorenzot/memento-core` — Motor de memoria
+- `@modelcontextprotocol/sdk` — SDK de Model Context Protocol
+- `zod` — Validacion de esquemas
 
-### Peer Dependencies
+### Runtime
 - `bun` v1.0+ (recomendado)
 - `node` v20+ (compatible)
 
-## 🛠️ Desarrollo
+## Desarrollo
 
 ```bash
 # Clonar el proyecto
@@ -451,9 +449,6 @@ cd memento/packages/mcp-server
 # Instalar dependencias
 bun install
 
-# Desarrollo
-bun run dev
-
 # Build
 bun run build
 
@@ -461,33 +456,50 @@ bun run build
 bun test
 ```
 
-## 📋 Changelog
-
-### [0.1.1] - 2024-04-04
-- **Fixed**: Actualización de dependencias core
-- **Fixed**: Corrección de método deleteObservation
-- **Updated**: Mejora en validación de parámetros
-
-### [0.1.0] - 2024-04-04
-- **Added**: Versión inicial del servidor MCP
-- **Added**: 15 herramientas de gestión de memoria
-- **Added**: Integración completa con Model Context Protocol
-- **Added**: Soporte para Claude Desktop y VS Code
-
-## 👤 Autor
-
-**Soulberto Lorenzo**  
+## Changelog
+
+### [2.0.9] — 2026-05
+- **Added**: Herramientas de Sync (`mem_sync_status`, `mem_sync_project`, `mem_logout`)
+- **Added**: Herramientas de Journal (`mem_journal_write`, `mem_journal_read`, `mem_journal_search`)
+- **Added**: Herramientas Pin/Lock (`mem_pin`, `mem_unpin`, `mem_lock`, `mem_unlock`)
+- **Added**: `mem_replace` para ediciones quirurgicas de substrings
+- **Added**: `mem_merge` para deduplicacion de observaciones
+- **Added**: `mem_session_summary` herramienta nativa
+- **Added**: `mem_context` para recuperacion rapida de contexto
+- **Added**: `mem_capture_passive` para extraccion de aprendizajes
+- **Added**: Modos de busqueda semantica e hibrida
+- **Added**: 6 nuevos tipos de observacion (summary, learning, pattern, architecture, config, preference)
+- **Changed**: `mem_delete` consolidado (soft/restore/permanent/list)
+- **Changed**: `mem_status` herramienta de diagnostico compuesta (all/health/stats/config/sessions)
+
+### [1.0.0] — 2025
+- **Changed**: Consolidacion de herramientas (26 → 16 herramientas activas)
+- **Changed**: `mem_delete` con parametro `action`
+- **Changed**: `mem_search` con parametro `sort`
+- **Changed**: `mem_status` herramienta de diagnostico compuesta
+- **Changed**: `mem_save` auto-sugiere topic_key
+
+### [0.1.1] — 2024-04-04
+- **Fixed**: Actualizacion de dependencias core
+- **Fixed**: Correccion de metodo deleteObservation
+
+### [0.1.0] — 2024-04-04
+- **Added**: Version inicial del servidor MCP
+- **Added**: 15 herramientas de gestion de memoria
+- **Added**: Integracion completa con Model Context Protocol
+
+## Autor
+
+**Soulberto Lorenzo**
 - GitHub: [@slorenzot](https://github.com/slorenzot)
 - Email: slorenzot@gmail.com
 
-## 📄 Licencia
+## Licencia
 
-Este paquete está bajo Licencia **Creative Commons Attribution-NonCommercial-NoDerivs 4.0 International**.
+Este paquete esta bajo Licencia **Creative Commons Attribution-NonCommercial-NoDerivs 4.0 International**.
 
 [Ver Licencia Completa](https://github.com/slorenzot/memento/blob/main/LICENSE)
 
 ---
 
-**⚠️ Importante**: Este paquete tiene licencia restrictiva. Respeta los términos de la licencia CC BY-NC-ND 4.0.
-
-**[📖 English version](./README.md)**
+**[English version](./README.md)**