@slorenzot/memento-core 0.7.0 → 2.0.0

package/README.md

@@ -6,68 +6,68 @@
 
 > Core memory engine with SQLite FTS5 search, session management, and observation persistence for AI coding agents.
 
-## 🚀 Instalación
+## 🚀 Installation
 
 ```bash
-# Using Bun (recomendado)
+# Using Bun (recommended)
 bun add @slorenzot/memento-core
 
 # Using npm
 npm install @slorenzot/memento-core
 ```
 
-## 💡 Uso Básico
+## 💡 Basic Usage
 
 ### TypeScript
 ```typescript
 import { MemoryEngine } from '@slorenzot/memento-core';
 
-// Inicializar motor de memoria
+// Initialize memory engine
 const memory = new MemoryEngine('./data/memento.db');
 
-// Crear una observación
+// Create an observation
 const observation = await memory.createObservation({
-  title: 'Decisión de arquitectura',
-  content: 'Usar SQLite como motor de base de datos',
+  title: 'Architecture decision',
+  content: 'Use SQLite as the database engine',
   type: 'decision',
   topicKey: 'architecture',
   projectId: 'my-project'
 });
 
-console.log('Observación guardada:', observation);
+console.log('Observation saved:', observation);
 ```
 
 ### Shell/Bun
 ```bash
-# Ejecutar script TypeScript con motor de memoria
+# Run TypeScript script with memory engine
 bun run memory-script.ts
 ```
 
-## 🔧 API Esencial
+## 🔧 Core API
 
-### Clase Principal
+### Main Class
 
 #### `MemoryEngine(dbPath?: string)`
 
-Constructor del motor de memoria.
+Memory engine constructor.
 
-**Parámetros:**
-- `dbPath` (opcional): Ruta al archivo de base de datos SQLite. Default: `'./data/memento.db'`
+**Parameters:**
+- `dbPath` (optional): Path to the SQLite database file. Default: `'./data/memento.db'`
 
-**Ejemplo:**
+**Example:**
 ```typescript
 const memory = new MemoryEngine('./custom/path.db');
 ```
 
 ---
 
-#### Métodos de Observaciones
+#### Observation Methods
 
 ##### `createObservation(data)`
 
-Crea una nueva observación en la memoria.
+Creates a new observation in memory.
 
-**Parámetros:**
+**Parameters:**
 ```typescript
 {
   title: string;
@@ -80,13 +80,13 @@ Crea una nueva observación en la memoria.
 }
 ```
 
-**Retorna:** `Promise<Observation>`
+**Returns:** `Promise<Observation>`
 
-**Ejemplo:**
+**Example:**
 ```typescript
 const observation = await memory.createObservation({
-  title: 'Bug encontrado',
-  content: 'Error de conexión al servidor',
+  title: 'Bug found',
+  content: 'Server connection error',
   type: 'bug',
   projectId: 'project-123',
   metadata: { severity: 'high', priority: 1 }
@@ -97,9 +97,9 @@ const observation = await memory.createObservation({
 
 ##### `search(params)`
 
-Busca observaciones usando búsqueda full-text FTS5.
+Searches observations using FTS5 full-text search.
 
-**Parámetros:**
+**Parameters:**
 ```typescript
 {
   query?: string;
@@ -111,18 +111,18 @@ Busca observaciones usando búsqueda full-text FTS5.
 }
 ```
 
-**Retorna:** `Promise<SearchResult>`
+**Returns:** `Promise<SearchResult>`
 
-**Ejemplo:**
+**Example:**
 ```typescript
 const results = await memory.search({
-  query: 'arquitectura base de datos',
+  query: 'database architecture',
   type: 'decision',
   projectId: 'project-123',
   limit: 10
 });
 
-console.log(`Encontrados ${results.total} observaciones:`);
+console.log(`Found ${results.total} observations:`);
 results.observations.forEach(obs => console.log(obs.title));
 ```
 
@@ -130,18 +130,18 @@ results.observations.forEach(obs => console.log(obs.title));
 
 ##### `getObservation(id)`
 
-Obtiene una observación por su ID.
+Gets an observation by its ID.
 
-**Parámetros:**
-- `id`: ID numérico de la observación
+**Parameters:**
+- `id`: Numeric ID of the observation
 
-**Retorna:** `Promise<Observation | null>`
+**Returns:** `Promise<Observation | null>`
 
-**Ejemplo:**
+**Example:**
 ```typescript
 const observation = await memory.getObservation(123);
 if (observation) {
-  console.log('Observación encontrada:', observation.title);
+  console.log('Observation found:', observation.title);
 }
 ```
 
@@ -149,19 +149,19 @@ if (observation) {
 
 ##### `updateObservation(id, updates)`
 
-Actualiza una observación existente.
+Updates an existing observation.
 
-**Parámetros:**
-- `id`: ID numérico de la observación
-- `updates`: Objeto con campos a actualizar
+**Parameters:**
+- `id`: Numeric ID of the observation
+- `updates`: Object with fields to update
 
-**Retorna:** `Promise<Observation>`
+**Returns:** `Promise<Observation>`
 
-**Ejemplo:**
+**Example:**
 ```typescript
 const updated = await memory.updateObservation(123, {
-  title: 'Título actualizado',
-  content: 'Contenido modificado'
+  title: 'Updated title',
+  content: 'Modified content'
 });
 ```
 
@@ -169,28 +169,28 @@ const updated = await memory.updateObservation(123, {
 
 ##### `deleteObservation(id)`
 
-Elimina una observación por su ID.
+Deletes an observation by its ID.
 
-**Parámetros:**
-- `id`: ID numérico de la observación
+**Parameters:**
+- `id`: Numeric ID of the observation
 
-**Retorna:** `Promise<void>`
+**Returns:** `Promise<void>`
 
-**Ejemplo:**
+**Example:**
 ```typescript
 await memory.deleteObservation(123);
-console.log('Observación eliminada');
+console.log('Observation deleted');
 ```
 
 ---
 
-#### Métodos de Sesiones
+#### Session Methods
 
 ##### `createSession(data)`
 
-Crea una nueva sesión para seguimiento de conversaciones.
+Creates a new session for conversation tracking.
 
-**Parámetros:**
+**Parameters:**
 ```typescript
 {
   projectId: string;
@@ -198,34 +198,34 @@ Crea una nueva sesión para seguimiento de conversaciones.
 }
 ```
 
-**Retorna:** `Promise<Session>`
+**Returns:** `Promise<Session>`
 
-**Ejemplo:**
+**Example:**
 ```typescript
 const session = await memory.createSession({
   projectId: 'my-project',
   metadata: { agent: 'claude', userId: 'user-123' }
 });
 
-console.log('Sesión iniciada:', session.uuid);
+console.log('Session started:', session.uuid);
 ```
 
 ---
 
 ##### `getSession(id)`
 
-Obtiene una sesión por su ID.
+Gets a session by its ID.
 
-**Parámetros:**
-- `id`: ID numérico de la sesión
+**Parameters:**
+- `id`: Numeric ID of the session
 
-**Retorna:** `Promise<Session | null>`
+**Returns:** `Promise<Session | null>`
 
-**Ejemplo:**
+**Example:**
 ```typescript
 const session = await memory.getSession(456);
 if (session) {
-  console.log('Sesión encontrada:', session.uuid);
+  console.log('Session found:', session.uuid);
 }
 ```
 
@@ -233,38 +233,38 @@ if (session) {
 
 ##### `endSession(id)`
 
-Finaliza una sesión activa.
+Ends an active session.
 
-**Parámetros:**
-- `id`: ID numérico de la sesión
+**Parameters:**
+- `id`: Numeric ID of the session
 
-**Retorna:** `Promise<Session>`
+**Returns:** `Promise<Session>`
 
-**Ejemplo:**
+**Example:**
 ```typescript
 const endedSession = await memory.endSession(456);
-console.log('Sesión finalizada:', endedSession.endedAt);
+console.log('Session ended:', endedSession.endedAt);
 ```
 
 ---
 
-#### Método de Cierre
+#### Close Method
 
 ##### `close()`
 
-Cierra la conexión con la base de datos.
+Closes the database connection.
 
-**Retorna:** `void`
+**Returns:** `void`
 
-**Ejemplo:**
+**Example:**
 ```typescript
-// En cleanup de aplicación
+// On application cleanup
 memory.close();
 ```
 
 ---
 
-## 📝 Tipos Principales
+## 📝 Core Types
 
 ```typescript
 interface Observation {
@@ -304,26 +304,26 @@ interface SearchResult {
 }
 ```
 
-## ⚡ Ejemplos Prácticos
+## ⚡ Practical Examples
 
-### Ejemplo 1: Flujo Completo de Memoria
+### Example 1: Complete Memory Workflow
 
 ```typescript
 import { MemoryEngine } from '@slorenzot/memento-core';
 
 const memory = new MemoryEngine('./memory.db');
 
-// Crear sesión para seguimiento
+// Create session for tracking
 const session = await memory.createSession({
   projectId: 'my-app',
   metadata: { agent: 'claude' }
 });
 
-// Guardar observaciones durante el trabajo
+// Save observations during work
 await memory.createObservation({
   sessionId: session.id,
-  title: 'Configuración de servidor',
-  content: 'Usar Express.js con middleware de seguridad',
+  title: 'Server configuration',
+  content: 'Use Express.js with security middleware',
   type: 'decision',
   projectId: 'my-app',
   topicKey: 'backend'
@@ -331,85 +331,85 @@ await memory.createObservation({
 
 await memory.createObservation({
   sessionId: session.id,
-  title: 'Bug en autenticación',
-  content: 'El JWT no expira correctamente',
+  title: 'Authentication bug',
+  content: 'JWT not expiring correctly',
   type: 'bug',
   projectId: 'my-app',
   topicKey: 'security'
 });
 
-// Buscar decisiones relacionadas
+// Search for related decisions
 const decisions = await memory.search({
   type: 'decision',
   projectId: 'my-app'
 });
 
-console.log('Decisiones tomadas:', decisions.observations);
+console.log('Decisions made:', decisions.observations);
 
-// Finalizar sesión
+// End session
 await memory.endSession(session.id);
 
-// Cerrar conexión
+// Close connection
 memory.close();
 ```
 
-### Ejemplo 2: Búsqueda Avanzada
+### Example 2: Advanced Search
 
 ```typescript
 import { MemoryEngine } from '@slorenzot/memento-core';
 
 const memory = new MemoryEngine('./memory.db');
 
-// Búsqueda compleja con múltiples filtros
+// Complex search with multiple filters
 const results = await memory.search({
-  query: 'base de datos arquitectura',
+  query: 'database architecture',
   type: 'decision',
   projectId: 'my-app',
   limit: 5,
   offset: 10
 });
 
-console.log(`Total de resultados: ${results.total}`);
+console.log(`Total results: ${results.total}`);
 results.observations.forEach((obs, index) => {
   console.log(`${index + 1}. ${obs.title}`);
   console.log(`   ${obs.content.substring(0, 100)}...`);
-  console.log(`   Tipo: ${obs.type} | Tópico: ${obs.topicKey}`);
+  console.log(`   Type: ${obs.type} | Topic: ${obs.topicKey}`);
 });
 
 memory.close();
 ```
 
-## ⚠️ Licencia Restrictiva
+## ⚠️ Restrictive License
 
-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**
+This package is under **CC BY-NC-ND 4.0 License**:
+- ✅ **Personal and educational use permitted**
+- ✅ **Share with attribution to the author**
+- ❌ **Commercial use NOT permitted**
+- ❌ **Modifications or forks NOT permitted**
 
-**Autor**: Soulberto Lorenzo (slorenzot@gmail.com)
+**Author:** Soulberto Lorenzo (slorenzot@gmail.com)
 
-## 🔄 Dependencias
+## 🔄 Dependencies
 
-### Dependencias Principales
-- `zod` - Validación de esquemas
-- `nanoid` - Generación de IDs únicos
+### Main Dependencies
+- `zod` - Schema validation
+- `nanoid` - Unique ID generation
 
 ### Peer Dependencies
-- `bun` v1.0+ (recomendado)
+- `bun` v1.0+ (recommended)
 - `node` v20+ (compatible)
 
-## 🛠️ Desarrollo
+## 🛠️ Development
 
 ```bash
-# Clonar el proyecto
+# Clone the project
 git clone https://github.com/slorenzot/memento.git
 cd memento/packages/core
 
-# Instalar dependencias
+# Install dependencies
 bun install
 
-# Desarrollo
+# Development
 bun run dev
 
 # Build
@@ -422,23 +422,25 @@ bun test
 ## 📋 Changelog
 
 ### [0.1.0] - 2024-04-04
-- **Added**: Versión inicial del motor de memoria
-- **Added**: SQLite con FTS5 para búsqueda full-text
-- **Added**: Gestión de sesiones y observaciones
-- **Added**: Soporte completo de TypeScript
+- **Added**: Initial version of the memory engine
+- **Added**: SQLite with FTS5 for full-text search
+- **Added**: Session and observation management
+- **Added**: Full TypeScript support
 
-## 👤 Autor
+## 👤 Author
 
-**Soulberto Lorenzo**  
+**Soulberto Lorenzo**
 - GitHub: [@slorenzot](https://github.com/slorenzot)
 - Email: slorenzot@gmail.com
 
-## 📄 Licencia
+## 📄 License
 
-Este paquete está bajo Licencia **Creative Commons Attribution-NonCommercial-NoDerivs 4.0 International**.
+This package is licensed under **Creative Commons Attribution-NonCommercial-NoDerivs 4.0 International**.
 
-[Ver Licencia Completa](https://github.com/slorenzot/memento/blob/main/LICENSE)
+[View Full License](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.
+**⚠️ Important:** This package has a restrictive license. Please respect the CC BY-NC-ND 4.0 license terms.
+
+**[📖 Spanish version (Versión en español)](./README.es.md)**

package/dist/ConfigManager.d.ts

@@ -1,12 +1,102 @@
+/** Legacy flat config format (.mementorc) */
 export interface MementoConfig {
     storageMethod?: 'database' | 'storage';
     dbPath?: string;
     storagePath?: string;
     projectId?: string;
 }
+/** New structured config format (.memento/config.json) */
+export interface MementoConfigV1 {
+    version: 1;
+    project: string;
+    database: {
+        path: string;
+        wal?: boolean;
+    };
+    defaults?: {
+        autoSeed?: boolean;
+        scope?: 'project' | 'personal';
+        session?: {
+            /** Max ms a session can be active before considered stale. Default: 86400000 (24h) */
+            staleThresholdMs?: number;
+        };
+    };
+}
+/** Default stale threshold: 24 hours in milliseconds */
+export declare const DEFAULT_STALE_THRESHOLD_MS: number;
+/** Options for creating a new config */
+export interface CreateConfigOptions {
+    project?: string;
+    dbPath?: string;
+    targetDir?: string;
+    force?: boolean;
+    global?: boolean;
+}
+/** Result of config creation */
+export interface CreateConfigResult {
+    configPath: string;
+    dbPath: string;
+    projectDir: string;
+    migrated: boolean;
+    backupPath?: string;
+}
+/** Result of config migration */
+export interface MigrateConfigResult {
+    success: boolean;
+    sourcePath: string;
+    targetPath: string;
+    backupPath: string;
+    config: MementoConfigV1;
+    error?: string;
+}
+declare const LEGACY_CONFIG_FILE = ".mementorc";
+declare const NEW_CONFIG_DIR = ".memento";
+declare const NEW_CONFIG_FILE = "config.json";
+declare const GLOBAL_CONFIG_DIR: string;
+declare const GLOBAL_CONFIG_PATH: string;
+/**
+ * Normalize a project identifier to a canonical form.
+ * - Lowercase
+ * - Replace spaces, underscores, and special chars with hyphens
+ * - Collapse multiple consecutive hyphens into one
+ * - Strip leading/trailing hyphens
+ *
+ * Examples:
+ *   "sura chile autos"           → "sura-chile-autos"
+ *   "suratech-salesforce-CL-app" → "suratech-salesforce-cl-app"
+ *   "my__cool  project"          → "my-cool-project"
+ *   "--leading-trailing--"       → "leading-trailing"
+ *   "  spaces  everywhere  "     → "spaces-everywhere"
+ */
+export declare function normalizeProjectId(name: string): string;
+/**
+ * Find project config searching upward from startDir.
+ * Priority: .memento/config.json → .mementorc (legacy)
+ */
 export declare function findProjectConfig(startDir?: string): MementoConfig | null;
+/**
+ * Find the raw config path (new or legacy format).
+ * Returns the absolute path to the config file found.
+ */
+export declare function findConfigPath(startDir?: string): string | null;
+/**
+ * Read the stale session threshold from V1 config.
+ * Returns DEFAULT_STALE_THRESHOLD_MS (24h) if not configured.
+ */
+export declare function getStaleThresholdMs(): number;
 export declare function loadConfig(): MementoConfig;
 export declare function resolveStoragePath(config: MementoConfig): string;
 export declare function resolveDbPath(config: MementoConfig): string;
 export declare function getProjectId(config: MementoConfig): string;
+/**
+ * Create a new config file (.memento/config.json or global).
+ * Returns the result with paths and whether migration occurred.
+ */
+export declare function createConfig(options?: CreateConfigOptions): CreateConfigResult;
+/**
+ * Migrate a legacy .mementorc to the new .memento/config.json format.
+ * Backs up the original file as .mementorc.bak.
+ */
+export declare function migrateConfig(sourceDir?: string): MigrateConfigResult;
+export { GLOBAL_CONFIG_DIR, GLOBAL_CONFIG_PATH, NEW_CONFIG_DIR, NEW_CONFIG_FILE, LEGACY_CONFIG_FILE };
 //# sourceMappingURL=ConfigManager.d.ts.map

package/dist/ConfigManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConfigManager.d.ts","sourceRoot":"","sources":["../src/ConfigManager.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,aAAa,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAwBD,wBAAgB,iBAAiB,CAAC,QAAQ,GAAE,MAAsB,GAAG,aAAa,GAAG,IAAI,CA0BxF;AAED,wBAAgB,UAAU,IAAI,aAAa,CA8B1C;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAYhE;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAY3D;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAS1D"}
+{"version":3,"file":"ConfigManager.d.ts","sourceRoot":"","sources":["../src/ConfigManager.ts"],"names":[],"mappings":"AAMA,6CAA6C;AAC7C,MAAM,WAAW,aAAa;IAC5B,aAAa,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,0DAA0D;AAC1D,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,CAAC,EAAE,OAAO,CAAC;KACf,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,KAAK,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;QAC/B,OAAO,CAAC,EAAE;YACR,sFAAsF;YACtF,gBAAgB,CAAC,EAAE,MAAM,CAAC;SAC3B,CAAC;KACH,CAAC;CACH;AAED,wDAAwD;AACxD,eAAO,MAAM,0BAA0B,QAAsB,CAAC;AAE9D,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,gCAAgC;AAChC,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,iCAAiC;AACjC,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,eAAe,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAUD,QAAA,MAAM,kBAAkB,eAAe,CAAC;AACxC,QAAA,MAAM,cAAc,aAAa,CAAC;AAClC,QAAA,MAAM,eAAe,gBAAgB,CAAC;AACtC,QAAA,MAAM,iBAAiB,QAA8B,CAAC;AAEtD,QAAA,MAAM,kBAAkB,QAA8C,CAAC;AAIvE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWvD;AAyCD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,GAAE,MAAsB,GAAG,aAAa,GAAG,IAAI,CAmCxF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,GAAE,MAAsB,GAAG,MAAM,GAAG,IAAI,CAmB9E;AAID;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAa5C;AAED,wBAAgB,UAAU,IAAI,aAAa,CA+B1C;AAID,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAYhE;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAY3D;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAW1D;AA6BD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,kBAAkB,CAwElF;AAID;;;GAGG;AACH,wBAAgB,aAAa,CAAC,SAAS,GAAE,MAAsB,GAAG,mBAAmB,CAkDpF;AAID,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,cAAc,EAAE,eAAe,EAAE,kBAAkB,EAAE,CAAC"}