@ancleto/spec 0.6.12 → 0.6.15

package/README.md

@@ -101,25 +101,23 @@ ancleto install --no-mcp
 ancleto update
 ```
 
-> El instalador configura por defecto los MCP locales **engram** y **caveman**. Si un binario no está en tu sistema, se omite con un warning sin interrumpir el flujo.
+> El instalador configura por defecto el MCP de **memoria propia** (`ancleto-memory`) y **caveman**. El MCP externo **engram** ya no se agrega por defecto: sumalo con `--with-engram` si además querés esa memoria. Si un binario no está en tu sistema, se omite con un warning sin interrumpir el flujo.
 
 ### Costo en tokens de los MCP
 
-Los MCP no son gratis en contexto: la lista de herramientas de cada servidor viaja en **cada** request, se usen o no. Medición local con el perfil mínimo de cada uno:
+Los MCP no son gratis en contexto: la lista de herramientas de cada servidor viaja en **cada** request, se usen o no. Medición local:
 
 | MCP | Herramientas | Tokens por request |
 |---|---|---|
-| engram (`--tools=agent`) | 18 | ~4.900 |
+| `ancleto-memory` (memoria propia) | 3 | ~500 |
 | caveman | 5 | ~830 |
-| **Total** | 23 | **~5.800** |
+| engram (solo con `--with-engram`) | 18 | ~4.900 |
 
-Cómo bajarlo si no los usás:
+Cómo bajarlo:
 
-- Instalá con `--no-mcp`.
-- O deshabilitá un servidor en tu `opencode.json`: `"mcp": { "engram": { "enabled": false } }`.
-- Engram permite elegir herramientas puntuales: `--tools=agent` ya es el perfil mínimo; las más pesadas de ese perfil son `mem_save` (~920), `mem_compare` (~590) y `mem_session_summary` (~490).
-
-> La memoria del framework (`.ancleto/memory.db`) es independiente de engram: funciona sin él. En los tiers `minimo` y `gratis` este overhead pesa proporcionalmente más que en `normal`.
+- Instalá con `--no-mcp` si no querés ninguno.
+- Evitá `--with-engram` salvo que uses esa memoria: es el que más pesa (9× la memoria propia).
+- Podés deshabilitar cualquier servidor en tu `opencode.json`: `"mcp": { "engram": { "enabled": false } }`.
 
 ---
 
@@ -192,6 +190,8 @@ ancleto memory context [--scope <project|feature|task>] [--out <archivo>]
 ancleto memory doctor [--rebuild]
                           # Diagnostica la base de memoria y reconstruye el índice FTS5
 
+ancleto mcp               # Servidor MCP de memoria propia (stdio): lo consume tu IDE
+
 ancleto discovery [--compress] [--include <glob>] [--ignore <glob>] [--token-budget <n>]
                           # Empaqueta el repo con Repomix según tu tier
 ```
@@ -200,17 +200,25 @@ ancleto discovery [--compress] [--include <glob>] [--ignore <glob>] [--token-bud
 
 ## Motor de memoria persistente
 
-No hay bases de datos vectoriales: es **SQLite nativo** con búsqueda full-text (FTS5) y ranking BM25.
+No hay bases de datos vectoriales: es **SQLite nativo** con búsqueda full-text (FTS5) y ranking BM25, en `.ancleto/memory.db`.
 
-El LLM dispone de tres herramientas:
+Funciona en tres piezas que comparten el mismo archivo:
+
+| Pieza | Qué hace |
+|---|---|
+| **Almacenamiento** | Reglas y decisiones con supersesión atómica por `memory_key` (una sola activa por clave). |
+| **Tools del LLM** (`ancleto mcp`) | Servidor MCP local, sin dependencias, que expone tres herramientas a tu IDE. |
+| **CLI** | `ancleto memory context` materializa el bloque `<ProjectMemoryRules>` y `ancleto memory doctor` verifica integridad y reconstruye el índice FTS5. |
 
 | Herramienta | Función |
 |---|---|
-| `searchMemory` | Recupera contexto de decisiones previas. |
-| `recordRule` | Guarda una regla arquitectónica de forma jerárquica (proyecto → feature → tarea). |
-| `recordDecision` | Registra el *por qué* de un cambio en el código. |
+| `searchMemory` | Recupera contexto de decisiones y reglas previas (búsqueda léxica BM25). |
+| `recordRule` | Guarda una regla o restricción permanente. |
+| `recordDecision` | Registra el *por qué* de una decisión. |
+
+Cada entrada tiene un `scope`: `project` (default, entra en `<ProjectMemoryRules>`), `feature` o `task`. El orquestador inyecta los bloques `<ProjectMemoryRules>` y `<ProjectTopology>` en el system prompt de tu agente desde el día cero —incluso sin reglas previas— para que no repita errores ya resueltos.
 
-El orquestador inyecta los bloques `<ProjectMemoryRules>` y `<ProjectTopology>` en el system prompt de tu agente desde el día cero —incluso sin reglas previas— para que no repita errores ya resueltos.
+> El mismo motor se puede consultar a mano desde la terminal: `ancleto memory context --scope project`.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ancleto/spec",
-  "version": "0.6.12",
+  "version": "0.6.15",
   "description": "Orquestador SDD liviano con subagentes optimizados para costo/tokens",
   "type": "module",
   "bin": {

package/src/cli/index.js

@@ -9,6 +9,7 @@ import { fileURLToPath } from 'node:url'
 import { homedir, tmpdir } from 'node:os'
 import { createMemoryEngine, defaultMemoryDbPath } from '../core/memory/engine.js'
 import { memoryDoctor } from '../core/memory/doctor.js'
+import { serveMemoryMcp } from '../core/memory/mcp-server.js'
 import { writeDiscoveryMap } from '../core/discovery.js'
 import { readProjectTier, buildRepomixArgs, tierTokenBudget } from '../core/repomix-tier.js'
 import { showBanner, selectOption, stopBanner } from './ui.js'
@@ -26,8 +27,9 @@ const HELP = `ancleto - orquestador SDD liviano con subagentes optimizados para
 Uso:
   ancleto install [--project <dir>]   Instala agents/commands/skills en opencode
                                    (global por defecto, o en .opencode/ del proyecto)
-                                   Configura los MCP engram + caveman por defecto
+                                   Configura el MCP de memoria propia + caveman por defecto
   ancleto install --no-mcp           Igual que install pero sin tocar config MCP
+  ancleto install --with-engram      Ademas configura el MCP externo engram (memoria opcional)
   ancleto install --tier <nivel>     normal | minimo | gratis (wizard interactivo en TTY)
   ancleto install --agent <nombre>    opencode | vscode | antigravity | cursor | roo (wizard si no esta guardado)
   ancleto update [--project <dir>]    Alias de install (re-instala sobre lo existente)
@@ -42,6 +44,8 @@ Uso:
                                    Imprime/escribe el bloque <ProjectMemoryRules> (reglas activas)
   ancleto memory doctor [--rebuild] Diagnostica .ancleto/memory.db (integridad, FTS5, unicidad)
                                     y reconstruye el indice FTS5 con --rebuild
+  ancleto mcp                           Servidor MCP de memoria propia (stdio) para tu IDE
+                                        expone searchMemory, recordRule y recordDecision
   ancleto check                         Verifica integridad de archivos instalados vs manifiesto
   ancleto doctor                        Diagnostica el entorno (Node, node:sqlite, opencode.json)
   ancleto --help                      Esta ayuda
@@ -107,18 +111,27 @@ function resolveBin(name, fallbacks = []) {
   return null
 }
 
-function buildDefaultMcp() {
+function resolveSelfCommand() {
+  return [process.execPath, join(__dirname, 'index.js'), 'mcp']
+}
+
+function buildDefaultMcp({ withEngram = false } = {}) {
   const mcp = {}
 
-  const engramFallbacks = [
-    join(homedir(), 'go', 'bin', binName('engram')),
-    join(homedir(), '.local', 'bin', binName('engram'))
-  ]
-  const engramBin = resolveBin('engram', engramFallbacks)
-  if (engramBin) {
-    mcp.engram = { type: 'local', enabled: true, command: [engramBin, 'mcp', '--tools=agent'] }
-  } else {
-    console.warn('ancleto: no se encontro engram (memoria) en PATH; se omitio su MCP')
+  // Memoria propia del framework: SQLite (.ancleto/memory.db) expuesta como tools MCP
+  mcp['ancleto-memory'] = { type: 'local', enabled: true, command: resolveSelfCommand() }
+
+  if (withEngram) {
+    const engramFallbacks = [
+      join(homedir(), 'go', 'bin', binName('engram')),
+      join(homedir(), '.local', 'bin', binName('engram'))
+    ]
+    const engramBin = resolveBin('engram', engramFallbacks)
+    if (engramBin) {
+      mcp.engram = { type: 'local', enabled: true, command: [engramBin, 'mcp', '--tools=agent'] }
+    } else {
+      console.warn('ancleto: no se encontro engram en PATH; se omitio su MCP')
+    }
   }
 
   const cavemanFallbacks = [
@@ -368,7 +381,7 @@ async function install(args) {
   const pi = args.indexOf('--project')
   const project = pi >= 0 ? args[pi + 1] : null
   const withMcp = !args.includes('--no-mcp')
-  let mcpMap = withMcp ? buildDefaultMcp() : {}
+  let mcpMap = withMcp ? buildDefaultMcp({ withEngram: args.includes('--with-engram') }) : {}
 
   const agentFlag = scanAgentFlag(args)
   let tier = scanTierFlag(args)
@@ -915,6 +928,9 @@ switch (cmd) {
   case 'doctor':
     await doctorCommand()
     break
+  case 'mcp':
+    await serveMemoryMcp()
+    break
   case '--version':
   case '-v':
     console.log(`ancleto ${await packageVersion()}`)

package/src/core/memory/database.js

@@ -7,7 +7,7 @@ const MIGRATIONS = [
     id TEXT PRIMARY KEY,
     memory_key TEXT NOT NULL,
     type TEXT NOT NULL CHECK (type IN ('rule', 'decision')),
-    scope TEXT NOT NULL DEFAULT 'repo',
+    scope TEXT NOT NULL DEFAULT 'project',
     status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'superseded', 'deleted')),
     content TEXT NOT NULL,
     justification TEXT NOT NULL DEFAULT '',

package/src/core/memory/engine.js

@@ -106,7 +106,7 @@ export function createMemoryEngine(dbPath = defaultMemoryDbPath()) {
     const type = input.type
     const content = String(input.content || '')
     const justification = String(input.justification || '')
-    const scope = String(input.scope || 'repo')
+    const scope = String(input.scope || 'project')
     if (!memory_key) throw new Error('memory_key es obligatorio')
     if (type !== 'rule' && type !== 'decision') throw new Error(`type invalido: ${type}`)
     if (!content.trim()) throw new Error('content es obligatorio')

package/src/core/memory/mcp-server.js

@@ -0,0 +1,98 @@
+import { createMemoryEngine, defaultMemoryDbPath } from './engine.js'
+import { memoryTools, createMemoryToolHandlers } from './tools.js'
+
+const PROTOCOL_VERSION = '2024-11-05'
+const SERVER_INFO = { name: 'ancleto-memory', version: '1.0.0' }
+
+export function createMemoryServer({ dbPath = defaultMemoryDbPath() } = {}) {
+  let engine = null
+  let handlers = null
+
+  function toolkit() {
+    if (!engine) {
+      engine = createMemoryEngine(dbPath)
+      handlers = createMemoryToolHandlers(engine, { source: 'mcp:ancleto-memory' })
+    }
+    return handlers
+  }
+
+  const respond = (id, result) => ({ jsonrpc: '2.0', id, result })
+  const fail = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } })
+
+  function handle(message) {
+    if (!message || typeof message !== 'object' || message.jsonrpc !== '2.0') return null
+    const { id, method, params } = message
+    if (typeof method === 'string' && method.startsWith('notifications/')) return null
+    if (id === undefined || id === null) return null
+
+    switch (method) {
+      case 'initialize':
+        return respond(id, { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: SERVER_INFO })
+      case 'ping':
+        return respond(id, {})
+      case 'tools/list':
+        return respond(id, { tools: memoryTools })
+      case 'tools/call': {
+        const name = params && params.name
+        const args = (params && params.arguments) || {}
+        const tool = toolkit()[name]
+        if (!tool) return fail(id, -32602, `tool desconocida: ${name}`)
+        try {
+          const result = tool(args)
+          return respond(id, { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] })
+        } catch (err) {
+          return respond(id, { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true })
+        }
+      }
+      default:
+        return fail(id, -32601, `metodo no soportado: ${method}`)
+    }
+  }
+
+  function close() {
+    if (engine) {
+      engine.close()
+      engine = null
+      handlers = null
+    }
+  }
+
+  return { handle, close, dbPath }
+}
+
+export async function serveMemoryMcp({ dbPath = defaultMemoryDbPath(), input = process.stdin, output = process.stdout } = {}) {
+  const server = createMemoryServer({ dbPath })
+  const write = (obj) => output.write(JSON.stringify(obj) + '\n')
+
+  let stopped = false
+  const stop = () => {
+    if (stopped) return
+    stopped = true
+    server.close()
+    try { input.pause() } catch {}
+  }
+
+  input.setEncoding('utf8')
+  let buffer = ''
+  input.on('data', (chunk) => {
+    buffer += chunk
+    const lines = buffer.split('\n')
+    buffer = lines.pop()
+    for (const line of lines) {
+      const text = line.trim()
+      if (!text) continue
+      let message
+      try {
+        message = JSON.parse(text)
+      } catch {
+        write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'JSON invalido' } })
+        continue
+      }
+      const response = server.handle(message)
+      if (response) write(response)
+    }
+  })
+  input.on('end', stop)
+  process.on('SIGINT', () => { stop(); process.exit(0) })
+  process.on('SIGTERM', () => { stop(); process.exit(0) })
+}

package/src/core/memory/tools.js

@@ -2,6 +2,12 @@ import { createMemoryEngine } from './engine.js'
 
 const KEY_DESCRIPTION = 'Clave conceptual estable (ej. "api-error-format"). Reusala para actualizar: la nueva version supersede automaticamente la anterior.'
 
+const SCOPE_SCHEMA = {
+  type: 'string',
+  enum: ['project', 'feature', 'task'],
+  description: 'Ambito: project (default, entra en <ProjectMemoryRules>), feature o task para algo mas acotado.'
+}
+
 const SEARCH_SCHEMA = {
   type: 'object',
   properties: {
@@ -19,7 +25,7 @@ const RECORD_RULE_SCHEMA = {
     memory_key: { type: 'string', description: KEY_DESCRIPTION },
     content: { type: 'string', description: 'Texto de la regla.' },
     justification: { type: 'string', description: 'Por que existe esta regla.' },
-    scope: { type: 'string', description: 'Ambito de aplicacion (default "repo").' }
+    scope: SCOPE_SCHEMA
   },
   required: ['memory_key', 'content'],
   additionalProperties: false
@@ -31,7 +37,7 @@ const RECORD_DECISION_SCHEMA = {
     memory_key: { type: 'string', description: KEY_DESCRIPTION },
     content: { type: 'string', description: 'La decision tomada.' },
     justification: { type: 'string', description: 'Justificacion de la decision.' },
-    scope: { type: 'string', description: 'Ambito de aplicacion (default "repo").' }
+    scope: SCOPE_SCHEMA
   },
   required: ['memory_key', 'content'],
   additionalProperties: false