agent-knowledge

Memoria y recuperación entre sesiones para asistentes de codificación de IA -- funciona con Claude Code, Cursor, OpenCode, Cline, Continue.dev y Aider sin configuración adicional. Base de conocimiento sincronizada con Git, búsqueda híbrida semántica+TF-IDF, auto-destilación con limpieza de secretos.

Benchmark: R@5 = 97.2% (sparse) / 98.8% (hybrid) en longmemeval_s y 86.0% (sparse) / 88.4% (hybrid) en la división más difícil longmemeval_m — el benchmark académico público LongMemEval (Wu et al. 2024, ICLR 2025), 500 preguntas completas por división, sin LLM, sin clave API, se ejecuta completamente sin conexión. +8.6pp a +13.2pp R@5 sobre la línea base oficial flat-bm25 del artículo en reproducción comparable. Tabla completa por categoría, instrucciones de reproducción y detalles de comparación con el artículo en bench/README.md.

Por qué

Las sesiones de codificación de IA son efímeras. Cuando una sesión termina, todo lo que aprendió (decisiones de arquitectura, ideas de depuración, contexto del proyecto) desaparece. La siguiente sesión comienza desde cero.

agent-knowledge resuelve esto con dos sistemas complementarios:

1. Base de conocimiento -- un repositorio de markdown sincronizado con Git de entradas estructuradas (decisiones, flujos de trabajo, contexto del proyecto) que persiste entre sesiones y máquinas.

2. Búsqueda de sesiones -- búsqueda de texto completo clasificada por TF-IDF en las transcripciones de sesiones de todas tus herramientas de codificación, para que los agentes puedan recordar lo que sucedió antes, independientemente de la herramienta utilizada.

Related MCP server: Doclea MCP

Herramientas compatibles

Las sesiones de todos los principales asistentes de codificación de IA se auto-descubren: si una herramienta está instalada, sus sesiones aparecen automáticamente.

No se necesita configuración. Se pueden agregar raíces de sesión adicionales mediante la variable de entorno AGENT_KNOWLEDGE_EXTRA_SESSION_ROOTS (rutas separadas por comas).

Características

• Búsqueda de sesiones independiente del host -- búsqueda unificada en todos los principales asistentes de codificación de IA (Claude Code, Cursor, Codex CLI, Aider, Continue.dev, Cline, OpenCode). Ningún nombre de host está integrado en la configuración: el registro de adaptadores sondea las raíces de host instaladas al inicio.

• Búsqueda híbrida -- similitud semántica de vectores combinada con clasificación de palabras clave TF-IDF.

• Base de conocimiento sincronizada con Git -- repositorio de markdown con frontmatter YAML, commit y push automáticos al escribir.

• Detección automática de obsolescencia -- knowledge_analyze(action: "stale_by_code_activity") cruza las rutas de archivo mencionadas en el cuerpo de cada entrada con filesModified en los resúmenes de sesiones recientes. Se combina con una capa de precisión de presencia de símbolos: los identificadores que la entrada cita (backticks en línea + bloques delimitados) se verifican en el archivo modificado; si aún existen, la confianza se reduce ×0.3. Las entradas con evergreen: true están exentas.

• Seguimiento de brechas de búsqueda -- knowledge_analyze(action: "search_gaps") muestra consultas sin resultados en los últimos since_days, agrupadas por similitud de token-Jaccard. La señal más clara de "¿qué entradas debería escribir a continuación?".

• Empaquetador de contexto por prioridad de sección -- knowledge(action: "wakeup") ensambla un paquete de múltiples secciones (identity → active_tasks → recent_decisions → known_gotchas → last_session_summary → top_weighted → semantic_fallback) dentro de un presupuesto de tokens (por defecto 800, anulable mediante token_budget o AGENT_KNOWLEDGE_WAKEUP_BUDGET). El presupuesto de sección no utilizado se redistribuye a secciones posteriores.

• Promotor puntuado y con compuertas -- las ideas de sesión se promueven mediante un puntuador ponderado de 6 señales con tres compuertas independientes (minScore, minRecallCount, minUniqueQueries). Se ejecuta automáticamente en segundo plano, a demanda mediante knowledge_admin(action: "promote"), o se puede evaluar sin conexión con npm run bench:promote. Emite un diario auditable .dreams/YYYY-MM-DD.md en cada ejecución.

• Sistema de adaptadores conectables -- agrega soporte para nuevas herramientas implementando la interfaz SessionAdapter.

• Embeddings -- proveedores locales (Hugging Face), OpenAI, Claude/Voyage o Gemini.

• Coincidencia difusa -- búsqueda tolerante a errores tipográficos usando distancia de Levenshtein.

• 6 ámbitos de búsqueda -- errores, planes, configuraciones, herramientas, archivos, decisiones.

• 6 herramientas MCP -- interfaz consolidada basada en acciones (knowledge, knowledge_search, knowledge_session, knowledge_graph, knowledge_analyze, knowledge_admin).

• Entradas perennes -- evergreen: true en el frontmatter exime a una entrada de la decadencia en la clasificación Y la hace de solo agregar bajo promoción. El panel muestra una insignia de chincheta en estas tarjetas.

• Atribución de autor -- el frontmatter opcional author: <string> se muestra como una etiqueta atenuada en cada tarjeta.

• Resolución de grafo de código -- tipos de arista calls, imports, inherits para estructura de código; recorrido BFS dirigido (outbound/inbound/both); bulk_link para ingesta eficiente; unlink_by_origin para limpiar aristas de código obsoletas antes de re-ingestar; IDs de nodo con prefijo code: distinguen código de conocimiento.

• Grafo de conocimiento temporal -- las aristas admiten ventanas de validez valid_from / valid_to; las consultas as_of devuelven instantáneas en un punto del tiempo; la acción invalidate marca hechos como finalizados sin eliminarlos.

• Impulsos de puntuación híbrida -- impulsos de nombres propios y proximidad temporal sobre la combinación TF-IDF + semántica, limitados a +66.7%, con cortocircuito cuando no hay señales presentes.

• Categoría como impulso (no filtro) -- opta por category_mode: "boost" para que una suposición de categoría incorrecta reduzca la clasificación en lugar de descartar la respuesta correcta.

• Indexación de sesiones verbatim -- fragmentos por mensaje (≥30 caracteres) incrustados en el almacén de vectores para que la conversación cruda sea recuperable; se alterna con AGENT_KNOWLEDGE_INDEX_VERBATIM=false.

• URL de git configurable -- knowledge_admin(action: "config") para configuración en tiempo de ejecución, persistida en la ubicación XDG/AppData.

• Persistencia entre máquinas -- el conocimiento se sincroniza mediante git, las sesiones se leen del almacenamiento local de cada herramienta.

• Panel en tiempo real -- explora, busca y administra en localhost:3423.

• Limpieza de secretos -- claves API, tokens, contraseñas y claves privadas se redactan automáticamente antes del push de git.

• Grafo de conocimiento -- aristas de relación entre entradas (related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on) con recorrido BFS.

• Puntuación de confianza/decadencia -- entradas puntuadas por frecuencia y recencia de acceso; auto-promoción de candidata a establecida a probada.

• Consolidación de memoria -- detección de duplicados TF-IDF al escribir (advierte de entradas similares) más knowledge_analyze(action: "consolidate") para escaneo de deduplicación por lotes.

• Ciclo de reflexión -- knowledge_analyze(action: "reflect") muestra entradas no conectadas y genera indicaciones estructuradas para que el agente identifique nuevas conexiones de grafo.

• Auto-enlace al escribir -- las nuevas entradas se enlazan automáticamente a las 3 entradas existentes más similares cuando la similitud de coseno > 0.7.

• Metadatos de confianza — entradas etiquetadas como extracted (escritas por el usuario) o inferred (auto-destiladas, multiplicador de clasificación de búsqueda 0.85×); el campo confidence_score lleva la certeza del modelo 0-1.

• Análisis de conocimiento — acciones de knowledge_analyze god_nodes (entradas más conectadas), bridges (conectores entre categorías), gaps (entradas aisladas).

• Resumen de conocimiento — knowledge_analyze(action: "brief") devuelve un resumen en caché de ~200 tokens (conceptos centrales, proyectos activos, decisiones recientes, recuentos de obsoletos y brechas) para la orientación al inicio de sesión.

• Procedencia de aristas -- las aristas del grafo rastrean origin (manual, auto-link, distill, reflect) para que el análisis pueda distinguir el juicio del usuario de las heurísticas automatizadas.

• Pre-extracción determinista en destilación -- los resúmenes de sesión ahora incluyen commits de git, patrones de error, URLs accedidas y paquetes modificados extraídos mediante regex de la salida de bash/herramientas (sin costo de LLM).

• Metadatos de frescura en cada resultado de búsqueda -- cada resultado de conocimiento lleva freshness: { body_age_days, last_accessed, access_count, verified_at, verification_age_days, evergreen }. El agente lee la señal de confianza y decide; no imponemos degradación de política.

• Ventanas de decadencia por categoría -- el filtro "No usado" y el gráfico por tipo respetan umbrales por categoría (proyectos 180d, personas 365d, decisiones 90d, flujos de trabajo 60d, notas 30d) para que el contenido con forma de identidad no parezca obsoleto solo porque no se relee semanalmente.

• Ganchos de ciclo de vida -- SessionStart auto-despertar + verificación de frescura de ingesta, UserPromptSubmit inyección dirigida del primer prompt, PreCompact aviso de vaciado de memoria + destilación, SessionEnd destilación. Seis scripts de gancho en total, todos con fallo abierto, cada uno activable mediante una variable de entorno AGENT_KNOWLEDGE_*. Ver docs/HOOKS.md.

• Reemplaza la auto-memoria del host -- en hosts con un sistema de memoria por sesión (el ~/.claude/projects/*/memory/ de Claude Code, similar en otros IDEs), enruta los hechos y comentarios duraderos del usuario a agent-knowledge en su lugar. La auto-memoria es local a la máquina e invisible para otras máquinas; agent-knowledge está sincronizado con git, es entre máquinas, buscable y aparece en el despertar. Ver la nota de integración de Claude Code en docs/USER-MANUAL.md.

Ingesta de código

La habilidad knowledge-ingest puebla o actualiza la base de conocimiento desde un directorio de código. Utiliza tree-sitter para la extracción estructural de cero tokens (clases, funciones, importaciones, grafos de llamadas, comentarios de justificación), luego agrupa archivos en subsistemas y crea entradas de conocimiento + aristas de grafo mediante las herramientas MCP existentes. Las ejecuciones posteriores son incrementales: solo se reprocesan los archivos modificados.

/knowledge-ingest ./my-project

Utiliza el estándar Agent Skills — funciona con Claude Code, OpenCode, Cursor, Codex CLI y Gemini CLI. Consulta la Guía de ingesta para más detalles.

Lenguajes compatibles: TypeScript, JavaScript, Python, Go, Rust, Java, C, C++.

Inicio rápido

Instalar desde npm

npm install -g agent-knowledge

O clonar desde el código fuente

git clone https://github.com/keshrath/agent-knowledge.git
cd agent-knowledge
npm install && npm run build

Opción 1: Servidor MCP (para agentes de IA)

Agrega a tu configuración de cliente MCP (Claude Code, Cline, etc.):

{
  "mcpServers": {
    "agent-knowledge": {
      "command": "npx",
      "args": ["agent-knowledge"]
    }
  }
}

El panel se inicia automáticamente en http://localhost:3423 en la primera conexión MCP.

Consulta la Guía de configuración para instrucciones específicas por cliente (Claude Code, Cursor, Windsurf, OpenCode).

Opción 2: Servidor independiente (para clientes REST/WebSocket)

node dist/server.js --port 3423

Herramientas MCP (6)

Base de conocimiento

Búsqueda

Forma de la respuesta: {mode: "general" | "scoped", sessions, knowledge}. El modo scoped devuelve knowledge: [] por diseño.

Ámbitos (scopes): errors, plans, configs, tools, files, decisions, all.

Controles de búsqueda:

• mmr: true aplica reordenación por Relevancia Marginal Máxima (elimina clústeres casi duplicados en el top-K). mmr_lambda 0-1, por defecto 0.7.

• category_mode: "boost" (por defecto) otorga a las entradas de la categoría coincidente un multiplicador de puntuación de 1.25× en lugar de descartar las que no coinciden. Pasa "filter" para un comportamiento de filtro estricto.

• explain: true adjunta score_components: {bm25, decay, maturity, confidence, category_boost, mmr_penalty} a cada resultado de conocimiento.

Sesiones

Grafo de conocimiento

Tipos de conocimiento: related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on Tipos de estructura de código: calls, imports, inherits

Direcciones de recorrido: outbound (source→target), inbound (target→source), both (por defecto, no dirigido)

Análisis

Administración

Promotor puntuado

Cada candidato a nivel de proyecto se puntúa según seis señales (relevancia 0.30, frecuencia 0.24, diversidad de consultas 0.15, actualidad 0.15, consolidación 0.10, riqueza conceptual 0.06) y se somete a compuertas con minScore ≥ 0.5, minRecallCount ≥ 2, minUniqueQueries ≥ 2. Las tres compuertas deben superarse. La auto-promoción en segundo plano se controla con el mismo indicador de configuración auto_distill; invócala bajo demanda con knowledge_admin(action: "promote").

• promote_mode: "explain" (por defecto) — puntúa y aplica compuertas a los candidatos, escribe un diario, NO toca la base de conocimiento.

• promote_mode: "apply" — promueve los candidatos que superan las compuertas, escribe un diario, hace git-commit.

• Cada ejecución deja ~/agent-knowledge/.dreams/YYYY-MM-DD.md con desgloses de señales por candidato y resultados de compuertas. El directorio con prefijo . está rastreado por git pero excluido de listado/búsqueda.

• Rehidratación fundamentada: se omite un candidato si su archivo de sesión de origen ya no existe en disco (evita promover contenido eliminado).

• Las entradas con frontmatter evergreen: true nunca se sobrescriben mediante promoción — la actividad se añade.

Banco de pruebas de escritura: npm run bench:promote — reproducción sin conexión con autoetiquetado por "referenciado en sesiones posteriores". Compara el promotor con compuertas con una línea base ingenua de "enviar todo", e informa de precisión / recall / F1. Úsalo para validar cambios de ponderación de señales o umbrales antes de implementarlos.

API REST

Arquitectura

graph LR
    subgraph Storage
        KB[(Knowledge Base<br/>~/agent-knowledge<br/>Git Repository)]
    end

    subgraph Session Sources
        CC[(Claude Code<br/>JSONL)]
        CU[(Cursor<br/>JSONL)]
        OC[(OpenCode<br/>SQLite)]
        CL[(Cline<br/>JSON)]
        CD[(Continue.dev<br/>JSON)]
        AI[(Aider<br/>MD / JSONL)]
    end

    subgraph agent-knowledge
        KM[Knowledge Module<br/>store / search / git]
        AD[Session Adapters<br/>auto-discovery]
        SE[Search Engine<br/>TF-IDF + Fuzzy]
        DS[Dashboard<br/>:3423]
        MCP[MCP Server<br/>stdio]
    end

    subgraph Clients
        AG[Agent Sessions]
        WB[Web Browser]
    end

    KB <-->|git pull/push| KM
    CC --> AD
    CU --> AD
    OC --> AD
    CL --> AD
    CD --> AD
    AI --> AD
    AD --> SE
    KM --> MCP
    SE --> MCP
    KM --> DS
    SE --> DS
    MCP --> AG
    DS --> WB

Grafo de conocimiento

Las entradas y los símbolos de código pueden conectarse mediante aristas tipadas y ponderadas almacenadas en una tabla SQLite dedicada edges. Se admiten once tipos de relación: 8 para aristas de conocimiento y 3 para estructura de código:

Conocimiento: related_to, supersedes, depends_on, contradicts, specializes, part_of, alternative_to, builds_on Estructura de código: calls, imports, inherits

• knowledge_graph(action: "link") crea o actualiza una arista (con fuerza opcional 0-1)

• knowledge_graph(action: "unlink") elimina aristas (opcionalmente filtradas por tipo)

• knowledge_graph(action: "list") lista aristas para una entrada o tipo de relación

• knowledge_graph(action: "traverse") realiza un recorrido BFS dirigido desde una entrada inicial. Admite direction (outbound, inbound, both) y filtro rel_type

• knowledge_graph(action: "bulk_link") crea aristas por lotes en una sola transacción (para ingesta de grafo de código)

• knowledge_graph(action: "unlink_by_origin") elimina todas las aristas con un origen específico (para limpiar aristas de código obsoletas antes de re-ingestar)

Grafo de código

Las aristas de estructura de código las crea la habilidad knowledge-ingest durante la ingesta del código base. Usan IDs de nodo con prefijo code::

code:src/auth/middleware.ts                    # file node
code:src/auth/middleware.ts::validateToken      # symbol node

Ejemplos de consulta:

# Who calls validateToken?
knowledge_graph({ action: "traverse", entry: "code:src/auth.ts::validateToken", direction: "inbound", rel_type: "calls", depth: 3 })

# What breaks if I change this function?
knowledge_graph({ action: "traverse", entry: "code:src/auth.ts::validateToken", direction: "inbound", rel_type: "calls", depth: 5 })

# Combined: callers + knowledge context (decisions, design rationale)
knowledge_graph({ action: "traverse", entry: "code:src/auth.ts::validateToken", depth: 2 })

Enlazado automático

Cuando knowledge con action: "write" crea o actualiza una entrada, automáticamente encuentra las 3 entradas existentes más similares mediante similitud coseno y crea aristas related_to para cualquier par que puntúe por encima de 0.7.

Puntuación de confianza y decadencia

Cada entrada de conocimiento tiene una puntuación de confianza registrada en la tabla SQLite entry_scores. Los resultados de búsqueda se clasifican usando:

finalScore = baseRelevance * 0.5^(daysSinceLastAccess / 90) * maturityMultiplier

Las entradas maduran automáticamente según el recuento de accesos:

Las entradas consultadas con frecuencia suben en los rankings de búsqueda; las entradas obsoletas decaen con el tiempo.

Capacidades de búsqueda

TF-IDF Ranking -- resultados puntuados por frecuencia de término-frecuencia inversa de documento. Los términos poco frecuentes aumentan la relevancia. Índice global en caché durante 60 segundos.

Fuzzy Matching -- distancia de edición de Levenshtein con ventana deslizante. Umbral configurable (por defecto 0.7).

Scoped Recall mediante knowledge_search con el parámetro scope:

Integraciones

Endpoint de escritura REST

POST /api/knowledge acepta { category, filename, content } y ejecuta el pipeline completo de escritura: git pull → escritura de archivo → índice de embeddings → auto-enlace → git push → comprobación de duplicados. Devuelve { path, autoLinks?, duplicateWarnings?, git } con estado 201.

Esto permite escrituras basadas en HTTP desde otros servicios sin una conexión MCP.

agent-tasks KnowledgeBridge

agent-tasks tiene un KnowledgeBridge integrado que envía automáticamente los artefactos de learning y decision a agent-knowledge al completar la tarea. Las entradas se guardan en decisions/ con etiquetas de frontmatter (agent-tasks, nombre del proyecto, tipo de artefacto), se indexan automáticamente con embeddings y se enlazan automáticamente a entradas similares. No se necesita configuración: si agent-knowledge se está ejecutando en localhost:3423, funciona.

Pruebas

npm test              # 563 tests across 35 files
npm run test:watch    # Watch mode
npm run lint          # ESLint on src/ and tests/
npm run typecheck     # tsc --noEmit
npm run check         # typecheck + lint + format + test

Variables de entorno

Todas las variables de entorno viven bajo el prefijo AGENT_KNOWLEDGE_*. No hay ningún nombre de host fijo: el registro de adaptadores detecta automáticamente los hosts de codificación de IA instalados (.claude, .cursor, .codex, .aider, .continue, OpenCode) sin configuración.

Núcleo

Embeddings

Claves de API

Las anulaciones con ámbito de proyecto prevalecen sobre las claves estándar. Establece cualquiera de las dos; la forma con ámbito te permite ejecutar agent-knowledge con una clave diferente a la del resto de tu entorno.

Hooks

Anulaciones de herramientas externas

Documentación

• Guía de configuración — instalación, configuración del cliente (Claude Code, OpenCode, Cursor, Windsurf), hooks, skills

• Guía de ingesta — skill de ingesta de código, extracción con tree-sitter, actualizaciones incrementales

• Arquitectura — estructura del código fuente, principios de diseño, esquema de base de datos

• Panel — vistas y funciones de la interfaz web

• Changelog

Licencia

MIT