AgenticMind

Conocimiento y memoria auditables y auto-mejorables para agentes de IA a través de MCP: respuestas con citas forzadas y un rastro de razonamiento reproducible, auto-alojado en Postgres.

GitHub

Prueba este MCPPatrocinado

Documentación

AgenticMind

La capa de conocimiento y memoria auditable y auto-mejorable para agentes de IA.

Respuestas fundamentadas con citas comprobables, un rastro de por qué completo para cada respuesta, y un corpus que se mejora a sí mismo — servido a cualquier agente a través de MCP. Sin claves, multilingüe y auto-alojable solo con Postgres.

Inicio rápido · Verlo funcionar · Herramientas de agente · Cómo funciona · Por qué · El Estándar ↗

_{Si esto es útil, una ⭐ ayuda a que otros lo encuentren — y nos dice que sigamos.}

No es "almacenamiento de memoria para un agente". AgenticMind es el sustrato al que un agente apunta cuando necesita respuestas en las que pueda confiar, un rastro que pueda auditar, y una base de conocimiento que se acumula.

La mayoría de la memoria de agentes es un almacén de vectores con save() y search(). Eso te compra recuperación difusa y cero responsabilidad: no puedes saber por qué volvió una respuesta, si está actualizada, o si una fuente siquiera la respalda. AgenticMind trata el conocimiento como un sustrato de primera clase, auditable y auto-mejorable — y lo expone a cualquier agente a través del Protocolo de Contexto de Modelo.

✨ Por qué AgenticMind

📌 Con citas obligatorias — cada afirmación en una respuesta está vinculada a una fuente numerada. Sin fuente, sin afirmación.
🔍 Totalmente auditable — un rastro de por qué reproducible para cada respuesta: qué se recuperó, clasificó y usó.
♻️ Auto-mejorable — las respuestas validadas se promueven de vuelta al corpus mediante un bucle de acumulación controlado por un juez, impulsado por señales programáticas (no pulgares humanos).
🧩 Recuperación por niveles — fragmentos → tarjetas de hechos tipadas → grafo de conocimiento; híbrido vectorial + texto completo, consciente de la actualidad.
🔐 Seguro por construcción — tokens MCP con alcance y privilegios mínimos, autenticación de cierre ante fallo, salvaguardas en la entrada y la salida.
🐘 Un solo almacén de datos — Postgres + pgvector maneja vectores, texto completo, el grafo (CTE recursivo) y la cola duradera. Sin Redis, sin Neo4j, sin dispersión de bases de datos vectoriales.

🔧 Cómo funciona

flowchart TD
  A["🤖 Agent"] -->|"MCP request"| R["Tiered retrieval<br/>pgvector + full-text + graph"]
  R --> Y["Citation-enforced synthesis"]
  Y -->|"grounded answer + [citations]"| A
  Y --> T[("Replayable why-trace")]
  Y -->|"programmatic signals"| L["Judge-gated compounding loop"]
  L -->|"promotes validated knowledge"| R

Una solicitud llega a través de MCP → el motor recupera en tres niveles → sintetiza una respuesta donde cada afirmación cita una fuente → registra un rastro reproducible → y alimenta señales programáticas en un bucle que promueve conocimiento validado de vuelta al corpus.

🎬 Verlo funcionar

Una llamada real a kl_ask_global contra un corpus sembrado con el Estándar de Producto Agentic. La pregunta tiene deliberadamente dos mitades — una que el corpus puede responder y otra que no:

A live kl_ask_global call: a citation-enforced answer that refuses the unsupported half, with a replayable why-trace

// → kl_ask_global
{ "question": "When should I use a multi-agent architecture instead of a single agent,
                and what must every agent ship with according to the standard?" }

// ← response (trimmed)
{
  "answer": "The provided sources do not specify when to use a multi-agent architecture
             versus a single agent. … According to the Agentic Product Standard, every
             agent must ship with a written Agent Contract [1]. This contract must cover
             ownership, forbidden actions, acceptance criteria, failure modes, escalation
             rules, and logging requirements [1].",
  "citations": [
    { "number": 1, "title": "Agent Contract requirement",
      "materialId": "ba44971b-…", "score": 0.46, "origin": "chunk" }
  ],
  "model": "google/gemini-3.1-flash-lite-preview",
  "retrievalMs": 606, "generationMs": 890,
  "phases": [ {"phase":"embed","ms":552}, {"phase":"retrieve","ms":37},
              {"phase":"synth","ms":890}, {"phase":"output_filter","ms":2} ],
  "telemetryId": "cc942e54-…"
}

Mira lo que no sucedió. La mitad que el corpus no pudo respaldar, el modelo se negó a responder — "las fuentes proporcionadas no especifican…" — en lugar de inventarla. La mitad que sí pudo respaldar está vinculada a una cita numerada que puedes abrir. Y cada respuesta viene con un rastro de por qué (phases, model, telemetryId) que puedes reproducir. Esa es toda la propuesta en una llamada: sin fuente, sin afirmación — y un recibo para cada respuesta.

🆚 En qué se diferencia

	RAG simple / SDKs de memoria	AgenticMind
Respuestas fundamentadas	a veces	con citas obligatorias + verificación posterior
Rastro de por qué por respuesta	✗	rastro de decisión completo
Corpus auto-mejorable	✗	bucle de acumulación (controlado por juez)
Verificación relacional	✗	módulo de grafo
Se ejecuta en	varía	Postgres + pgvector (principal)

✅ Úsalo cuando / 🚫 busca otra cosa cuando

Usa AgenticMind cuando:

Tu agente debe responder desde fuentes confiables, y cada afirmación necesita una cita.
Necesitas un rastro de por qué reproducible y un único status (respaldado / parcial / no respaldado / en conflicto / requiere_revisión) en el que puedas condicionar a un agente.
Las fuentes en desacuerdo o desactualizadas deben salir a la superficie, no resolverse en silencio.
Quieres auto-mejora gobernada — no mutación de memoria autónoma silenciosa.
Necesitas auto-alojamiento (solo Postgres) y acceso nativo MCP (Claude Code, Cursor, LangGraph, OpenAI/Claude Agent SDK, agentes personalizados).

Busca otra cosa cuando:

Solo necesitas memoria de chat personalizada simple (usa un SDK de memoria).
Quieres una API alojada / UI sin código hoy — AgenticMind es infraestructura auto-alojada.
Necesitas SSO / SOC2 listos para usar (consulta el modelo de seguridad para lo que existe).
Estás optimizando para el prototipo más rápido, no para producción responsable.

🛠 Superficie de agente (MCP)

Un servicio sin interfaz (apps/server) expone el motor como herramientas MCP a través de HTTP transmisible, con autenticación de portador por token con cierre ante fallo (con alcance, privilegios mínimos):

Herramienta	Alcance	Propósito
`kl_search`	`knowledge:read`	búsqueda de pasajes semántica / por palabras clave
`kl_ask_global`	`knowledge:read`	respuesta sintetizada + citas + un `status` condicionable (opcional `intent`/`facts`)
`kl_get_material`	`knowledge:read`	obtener un material por id
`kl_graph_neighbors`	`knowledge:read`	materiales relacionados a través del grafo de conocimiento
`kl_ingest`	`knowledge:write`	agregar texto (fragmentado, incrustado, destilado en tarjetas, extraído al grafo)
`kl_forget`	`knowledge:admin`	eliminar un material + todos los fragmentos/tarjetas/grafo derivados (inverso de ingesta)
`kl_signal`	`knowledge:signal`	emitir una señal programática de acumulación sobre una respuesta anterior
`mem_recall`	`memory:read`	recordar creencias (privadas ∪ compartidas); semántico o `asOf` viaje en el tiempo
`mem_write`	`memory:write`	registrar una creencia en memoria privada (bitemporal, consciente de revisiones)
`mem_forget`	`memory:write`	retractar una de tus propias creencias (suave, bitemporal)

Consulta Qué cuenta como conocimiento para el contrato de Unidad de Conocimiento (qué puede convertirse en conocimiento almacenado), Evaluaciones y límites para lo que medimos y lo que no afirmamos, docs/knobs.md para los controles opcionales de calidad de respuesta (fidelidad de Nivel B, fuentes en conflicto, política de respuesta, confianza de fuentes), y el modelo de seguridad (autenticación de cierre ante fallo, RLS de inquilino, análisis de tríada letal, cadena de suministro).

No hay interfaz de usuario — los únicos consumidores son agentes a través de MCP. La lógica de herramientas es agnóstica al framework en packages/shared/src/lib/knowledge/mcp-tools.ts; el host es un manejador fetch estándar web de ~60 líneas servido por Node o Bun.

🚀 Inicio rápido

Ejecútalo — sin clonar (~1 min)

Necesita Docker (Compose v2.23+) y una clave compatible con OpenAI. Un comando extrae las imágenes publicadas, genera secretos, levanta Postgres + servidor + trabajador, e imprime una configuración MCP lista para pegar — sin clonar el repositorio, sin acuñar tokens:

OPENAI_API_KEY=sk-... sh -c "$(curl -fsSL https://raw.githubusercontent.com/Moai-Team-LLC/AgenticMind/main/quickstart.sh)"

El endpoint MCP se levanta en http://localhost:3000/mcp, autenticado con un único portador estático (MCP_API_KEY, generado automáticamente). Apunta Claude Code / Cursor a él con el encabezado Authorization: Bearer <MCP_API_KEY>.

Las incrustaciones se ejecutan localmente por defecto — un modelo multilingüe sin claves y sin conexión (bge-m3) se descarga en el primer uso, por lo que la recuperación no necesita clave en la nube. Solo el paso de síntesis necesita un modelo de chat: OPENAI_API_KEY para OpenAI (el predeterminado), o apunta CHAT_BASE_URL a cualquier endpoint compatible con OpenAI — un Ollama local o vLLM.

La imagen Docker publicada lee OPENAI_API_KEY y lo mapea al CHAT_API_KEY del servidor internamente; la ruta desde el código fuente a continuación establece CHAT_API_KEY directamente en .env.local — el mismo secreto, solo nombrado para cada punto de entrada.

¿Prefieres leer antes de ejecutar? Lo mismo, explícito (solo el reemplazo de deploy/, sin clonación completa):

mkdir agenticmind && cd agenticmind
curl -fsSL https://raw.githubusercontent.com/Moai-Team-LLC/AgenticMind/main/deploy/docker-compose.yml -o docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/Moai-Team-LLC/AgenticMind/main/deploy/.env.example       -o .env.example
curl -fsSL https://raw.githubusercontent.com/Moai-Team-LLC/AgenticMind/main/deploy/gen-secrets.sh     -o gen-secrets.sh && chmod +x gen-secrets.sh
./gen-secrets.sh                   # writes DB password + MCP_API_KEY into .env
# set OPENAI_API_KEY in .env, then:
docker compose up -d

Desde el código fuente (desarrollo y contribuciones)

Requiere Docker y Node ≥22.18 (o Bun ≥1.3) — el servidor y el trabajador se ejecutan en Node o Bun puros.

git clone https://github.com/Moai-Team-LLC/AgenticMind.git
cd AgenticMind
cp .env.example .env.local         # set AUTH_SECRET (+ a chat key OR local Ollama)
./setup.sh                         # picks npm or bun, starts Postgres, runs migrations
npm run dev                        # headless MCP server on :3000  (or: bun run dev)

Verifica la compilación con npm run check (verificación de tipos + pruebas) — bun run check también funciona.

En una configuración de desarrollo desde el código fuente, la ruta /mcp tiene cierre ante fallo y acepta un portador JWT HS256 typ="mcp" (en lugar de la clave de implementación estática). El servidor sin interfaz no incluye UI de administración — acuña una con el script de emisión (lee DATABASE_URL + AUTH_SECRET de tu .env.local):

npm run issue-token -- --label "claude-code" --ttl-days 365   # or: bun run issue-token --label …
# prints the bearer on the last line — capture it, it is not stored in plaintext

Luego apunta un cliente MCP a http://localhost:3000/mcp con ese token como encabezado Authorization: Bearer …. (El lint adicionalmente requiere Node ≥22.18 — consulta .nvmrc.)

Nota. El Postgres Docker local no tiene TLS, por lo que .env.example incluye DATABASE_SSL=false y DATABASE_URL en el puerto del host 5435. Para Postgres administrado (Supabase, RDS, …) que requiere SSL, establece DATABASE_SSL=true.

🧱 Estructura

packages/shared/src/lib/knowledge/        ← the tiered engine (the product)
packages/shared/src/lib/ai/               ← chat + embeddings (provider-agnostic; local embeddings by default)
packages/shared/src/database/             ← Drizzle schema + queries (Postgres + pgvector)
apps/server/src/{index,mcp}.ts            ← headless MCP host, Node or Bun (agent surface)
apps/worker/src/jobs/knowledge-feedback/  ← Postgres-scheduled compounding sweep

Notas de arquitectura. Primero el agente y solo Postgres: el grafo vive detrás de una interfaz GraphStore (recorrido CTE recursivo en Postgres, sin servicio adicional), la acumulación se impulsa por señales programáticas, los tokens MCP tienen alcance de privilegios mínimos, el principal del agente es delgado, y el host es un servidor HTTP Node/Bun sin interfaz. La recuperación es multilingüe por defecto — las incrustaciones locales bge-m3 cubren muchos idiomas con cero claves; la búsqueda de texto completo usa la configuración simple agnóstica al idioma (configurable por implementación).

🌐 El ecosistema AgenticProduct

Un estándar y cinco implementaciones de referencia que puedes ejecutar — juntas cierran el bucle que todo agente de producción necesita: ejecutar → recordar → medir, con seguridad como un plano de aseguramiento transversal.

	Proyecto	Rol
📐	agentic-product-standard	El contrato — principios, la escalera de autonomía, las capas de arnés y la disciplina de evaluación (además de un conjunto de habilidades de Claude Code).
⚙️	AgenticOps	Runtime y operaciones — manifiestos implementables, programación, un backlog duradero, un ejecutor acotado y salud de la flota.
🧠	AgenticMind (este repositorio)	Conocimiento y memoria — auditable, auto-mejorable, con citas obligatorias, a través de MCP; solo Postgres.
📈	AgenticPerformance	Evaluaciones y observabilidad — trazas OTel, evaluaciones de conjunto dorado con puerta de CI, clústeres de fallos y el bucle de mejora.
🌉	AgenticGateway	Plano de modelo y costo — una clave, enrutamiento medido, límites, caché, evidencia.
🛡️	AgenticAssurance	Seguridad y aseguramiento — red-teams a cualquier agente (OWASP Agentic + MITRE ATLAS), un grafo de flujo tóxico y salida SARIF.

Cómo se componen. AgenticOps ejecuta la flota, AgenticMind da a los agentes conocimiento y memoria auditables, y AgenticPerformance mide cada ejecución con trazas y evaluaciones — cerrando el bucle ejecutar → recordar → medir. AgenticGateway es el plano de modelo por el que pasa cada llamada LLM en ese bucle — una clave, enrutamiento medido por evaluación, límites de costo — y AgenticAssurance red-teams a cualquier agente en el bucle, con toda la pila conforme al agentic-product-standard.

Consulta el estudio de caso de AgenticMind del estándar para un mapa capa por capa de cómo este repositorio implementa el canon.

🤝 Contribuciones y licencia

Contribuciones bienvenidas — consulta CONTRIBUTING.md. Licenciado bajo Apache-2.0.