khwan-mcp

Memoria duradera que sobrevive a la sesión. Un servidor MCP que conecta Khwan — una capa de memoria de IA pura — con Claude Code, Claude Desktop o cualquier cliente MCP.

Khwan nunca ejecuta un modelo. El cliente es el modelo. L'trabajo de Khwan es persistir y destilar lo que importa en un cerebro que puedes recordar en una sesión posterior o con el que inicializar un subagente — un conjunto compacto y acota de hechos en lugar de uno transcrito (no basta). Una cuenta puede contener much núcleos (cerebros) aislados — and en los planes de pago — a subcerebro aislado por usuario final.

Cómo ahorra tokens (y dónde no)

Be honestos about el mechanismo — un MCP añáde al contexto es de host, no reemplaza el histórico que al host ya sent. Entonces:

• Dentnt de una misma sesión active, no ahorra tokens. Claude Cod cachea su historial crecienté (reads de cache ≈ 0.1×), así que re-inyectar memoria en cada turno only adicion. No lo hagas opts.

• Entre sesi here "subagentes", sí. Una cache muere ofión minutes; una sesión termina. Khwan persiste hechos destilados on que la siguiente ejecución los recorte cheapy — sin volver a reproducir en frío un transcipto antiguo, and los hechos que yahan fuera del contexto son recupableo.

El patrón óptimo in tokens: inicializa una vez, recuerda hechos duraderos (abajo), en lugar de exejectar el bulge completo atel every turn. El bulge completo prepare → record es quien-mo de shine en un agente persistaliado en un host sin caché, where reemplazar historia with distiled memoria acota directamente el coste per turno.

Related MCP server: LedgerMem MCP Server

Instalación

pip install khwan-mcp          # or: uvx khwan-mcp

Conquer con Claude Code

claude mcp add khwan --scope project \
  -e KHWAN_CORE=default \
  -- khwan-mcp

--socope project escribe .mcp.json en el repositorio, así que la configración vija con el proyect. Note what is pue in ese comando: la cla.

Manterner la cla fuere del repostoriorio

claude mcp add -e KHWAN_API_KEY=… escribe el valor literal en .mcp.json — unno file cuyo punto es que sea commited. Dos maneras de evitarlo, and la segunda es la que funciona en todos:

Entorno del shell. Deja KH_API_KEY por fuera enter the config in and export ite in the shell that launches claude. The server inherits it.

export KHWAN_API_KEY=kwk_live_xxx

Un launcher (or funciióning en el escritorio app also). A escritorio app is launched from a dock or menu, no from a login shell, so it inherits none of your shell exports and the above method runs in silence no key. Read it from a file instead:

mkdir -p ~/.khwan && chmod 700 ~/.khwan
printf 'KHWAN_API_KEY=kwk_live_xxx\n' > ~/.khwan/env && chmod 600 ~/.khwan/env

cat > ~/.khwan/khwan-mcp <<'SH'
#!/bin/sh
set -a
[ -f "$HOME/.khwan/env" ] && . "$HOME/.khwan/env"
set +a
exec khwan-mcp "$@"
SH
chmod 700 ~/.khwan/khwan-mcp

Then point the config to the launcher and keep only the non-secret settings in line:

claude mcp add khwan --scope project \
  -e KHWAN_CORE=acme -e KHWAN_USER=Web \
  -- ~/.khwan/khwan-mcp

.mcp.json is now secure to commit, and every new repo costs two lines instead of a pasted key. Any other person on the team writes their own ~/.khwan/env.

Un cerebro por proyecto

The memory is only useful if the right project memory returns. Two axes, and both give complete isolation:

A subcerebro is a completely separate brain, not a filter: account::acme::@Web does not share anything with account::acme::@Api. So a client with several repositories can be one core with a subbrain in each, instead of a core in each:

GXPI6

The cores must exist before you can point to one — an unknown core answers 404. Create them in the management panel. The sub-brains are created in the first writing.

Recommended pattern (efficient tokens)

On a host with caching like Claude Code, prefer initialize + remember over the loop per turn:

1. While initiala at the beginning of a palm:

   "Call khwan_recall(query="<the task>") and use the seed_text returned to understand context."

2. Records the durable moments as they emerge:

   "That is a fixed decision — call khwan_remember(conceptual="…")."

You reinforce it in your CLAUDE.md of your project, e.g.:

- At the start of a task, call `khwan_recall` to seed relevant memory.
- When a durable decision/preference/fact emerges, call `khwan_remember`.
- Don't call prepare/record every turn — it adds tokens without saving them here.

Initalize a subagent is where the win is clearer: give it a short limited briefing instead of the whole transcript:

"Recueres memory of deployment with khwan_recall(consulta="deploy runbook") and then starts a subagent whose summary is that seed_text as well as the task."

Connect with Claude Desktop

Claude Desktop and Claude Code are separate MCP configurations. A server added to one invisible to the other, and claude mcp add does not touch this file. Add it to claude_desktop_config.json:

GXPB

Use a relative path: a desktop app does not inherit your PATH from shell, so a bare khwan-mcp may not resolve. One core is selected for the whole application — there is no per-project switching here, so choose a broad one.

Configuration (environment)

We need not be sloppy. I will now craft final clean translation properly.

Let's abort and produce a clean final answer.# khwan-mcp

Memoria duradera que sobrevive a la sesión. Un servidor MCP que conecta Khwan — una capa de memoria de IA pura — con Claude Code, Claude Desktop o cualquier cliente MCP.

Khwan nunca ejecuta un modelo. El cliente es el modelo. Su trabajo es persistir y destilar lo que importa en un cerebro que puedes recuperar en una sesión posterior o inicializar un subagente con él: un conjunto compacto y acotado de hechos en lugar de una transcripción reproducida. Una cuenta puede contener muchos núcleos (cerebros) aislados y, en los planes de pago, un subcerebro aislado por usuario final.

Cómo ahorra tokens (y dónde no)

Seamos honestos sobre el mecanismo: un MCP añade al contexto del host, no reemplaza la transcripción que el host ya envía. Entonces:

• Dentro de una sesión activa, no ahorra tokens. Claude Code almacena en caché su histórico creciente (lecturas de caché ≈ 0.1×), así que reinyectar memoria en cada turno solo añade. No lo hagas aquí.

• Entre sesiones y subagentes, sí. Una caché muere en minutos; una sesión termina. Khwan persiste hechos destilados para que la siguiente ejecución los recupere con un coste bajo — sin volver a reproducir en frío una transcripción antigua, y los hechos que ya quedaron fuera del contexto se pueden recuperar de nuevo.

El patrón que ahorra tokens: inicializa una vez, recuerda hechos duraderos (ver abajo), en lugar de ejecutar el bucle completo en cada turno de un host con caché. El bucle completo prepare → record brilla en un agente personalizado sobre un host sin caché, donde sustituir la transcripción por memoria destilada limita directamente el coste por turno.

Instalación

pip install khwan-mcp          # or: uvx khwan-mcp

Conectar con Claude Code

claude mcp add khwan --scope project \
  -e KHWAN_CORE=default \
  -- khwan-mcp

--scope project escribe .mcp.json en el repositorio, así que el ajuste viaja con el proyecto. Observa lo que no está en ese comando: la clave.

Mantener la clave fuera del repositorio

claude mcp add -e KHWAN_API_KEY=… escribe el valor literal en .mcp.json, un archivo cuyo sentido es ser commiteado. Dos maneras de evitarlo: la segunda es la que funciona en todas partes.

Entorno del shell. Deja KHWAN_API_KEY fuera de la configuración y experta en el shell que lanza claude. El servidor la hereda.

export KHWAN_API_KEY=kwk_live_xxx

Un launcher (también funciona en la app de escritorio). Una app de escritorio se abre desde el dock o un menú, no desde un shell de login, así que no hereda ninguna exportación de tu shell y el método anterior se queda sin clave. Lela desde un archivo en su lugar:

mkdir -p ~/.khwan && chmod 700 ~/.khwan
printf 'KHWAN_API_KEY=kwk_live_xxx\n' > ~/.khwan/env && chmod 600 ~/.khwan/env

cat > ~/.khwan/khwan-mcp <<'SH'
#!/bin/sh
set -a
[ -f "$HOME/.khwan/env" ] && . "$HOME/.khwan/env"
set +a
exec khwan-mcp "$@"
SH
chmod 700 ~/.khwan/khwan-mcp

Luego apunta la configuración al launcher y deja solo los ajustes no secretos en línea:

claude mcp add khwan --scope project \
  -e KHWAN_CORE=acme -e KHWAN_USER=Web \
  -- ~/.khwan/khwan-mcp

.mcp.json ya es seguro para hacer commit, y cada repositorio nuevo cuesta dos líneas en lugar de una clave pegada. Cualquier otra persona del equipo escribe su propio ~/.khwan/env.

Un solo cerebro por proyecto

La memoria solo es útil si vuelve la memoria del proyecto correcto. Dos ejes, y ambos dan un aislamiento completo:

Un subcerebro es un cerebro completamente separado, no un filtro: account::acme::@Web no comparte nada con account::acme::@Api. Así, un cliente con varios repositorios puede ser un núcleo con un subcerebro por cada uno, en lugar de un núcleo por proyecto:

# in ~/code/acme-web
claude mcp add khwan --scope project -e KHWAN_CORE=acme -e KHWAN_USER=Web -- ~/.khwan/khwan-mcp
# in ~/code/acme-api
claude mcp add khwan --scope project -e KHWAN_CORE=acme -e KHWAN_USER=Api -- ~/.khwan/khwan-mcp

Los núcleos deben existir antes de señalar uno: un núcleo desconocido responde con 404. Créalos en el panel de control. Los subcerebros se crean en la primera escritura.

Patrón recomendado (optimización de tokens)

En un host con caché como Claude Code, prefiere inicializar + olvidar antes que el bucle por turno:

1. Inicializa al inicio de una sesión o subagente:

   "Llamar a khwan_recall(query="<tarea>") y usar el seed_text devuelto como contexto".

2. Recuerda los hechos duraderos a medida que aparecen:

   "Eso es una decisión fija — llama a khwan_remember(fact="…")."

Refuérzalo en tu CLAUDE.md del proyecto, por ejemplo:

- At the start of a task, call `khwan_recall` to seed relevant memory.
- When a durable decision/preference/fact emerges, call `khwan_remember`.
- Don't call prepare/record every turn — it adds tokens without saving them here.

Inicializar un subagente es donde la ventaja es más clara: dale un resumen acotado en lugar de toda la transcripción:

"Recupera la memoria de despliegue con khwan_recall(query: "deploy runbook"), y luego lanza un subagente cuya breve sea ese seed_text más la tarea."

Conectar con Claude Desktop

Claude Desktop y Claude Code tienen configuraciones MCP independientes: un servidor añadido a una no está visible para la otra, y claude mcp add no toca ese archivo. Añade lo siguiente a claude_desktop_config.json:

{
  "mcpServers": {
    "khwan": {
      "command": "/Users/you/.khwan/khwan-mcp",
      "env": {
        "KHWAN_CORE": "acme",
        "KHWAN_USER": "Web"
      }
    }
  }
}

Usa una ruta absoluta: una aplicación de escritorio tampoco recibe el PATH de tu shell, así que un simple khwan-mcp puede no resolverse. Se selecciona un núcleo para toda la aplicación; no existe un selector por proyecto, así que elige uno un amplio.

Configuración variables de entorno

Herramientas

khwan_recall / khwan_remember son el par que optimiza tokens para un host con caché; khwan_prepare / khwan_record son el bucle completo para agentes personalizados (pasa el mismo turn_token de prepare a record).

Lo que se devuelve, y qué significa una respuesta vacía

khwan_recall devuelve como máximo tres hechos — ese límite lo fija el servidor, así que limit puede bajarlo pero no subirlo — además de las lessons que la síntesis haya extraído de muchísimos turnos anteriores. Las lecciones van primero en el seed_text: una regla aprendida durante meses prevalece sobre un turno que casualmente está cerca en el índice.

La recuperación aplica un umbral de relevancia, por lo que una lista facts vacía es una respuesta: el cerebro no tiene nada cercano a esa pregunta. Tómala como "no se sabe aquí" en lugar de como un fallo, y no intentes llenar el vacío con el hecho que esté más cerca.

El umbral es deliberadamente laxo, porque un recuerdo descartado por error es invisible, mientras que uno conservado por error no lo es. Espera que el hecho devuelto sea algo plausiblemente relacionado, no ciertamente relevante; léelo antes de confiar en él.

Inicializar un cerebro a partir de trabajo ya realizado

Un cerebro nuevo no sabe nada, así que sus primeras semanas de recuperación serán escasas — mientras que las respuestas suelen estar ya en las transcripciones del propio host, sin leer. examples/backfill/ reproduces las transcripciones de Claude Code a un cerebro: determinista, sin usar modelos y con fun simple seco (dry-run) por defecto.

python3 examples/backfill/backfill_claude_code.py --map cores.json

Memoria siempre activa (hooks de Claude Code)

Las herramientas anteriores se llaman cuando Claude lo decide. Para una memoria determinista — sin depender del modelo — uso el preset de hooks de examples/claude-code-hooks/: un hook UserPromptSubmit inyecta memoria en cada turno y un hook Stop registra cada respuesta.

⚠️ En un host con caché, esta es la opción exhaustiva, no la barata: añade tokens por cada turno. Prefiérela cuando la fiabilidad del recuerdo importe más que el coste en tokens (o en un cliente sin caché); en caso contrario, usa khwan_recall al comienzo de la sesión.

Fuente

github.com/khwanlabs/khwan-mcp — este servidor se ejecuta en tu maquina, con tu clave y leyendo lo que writes. Lolo antes de instalarlo.

Licencia

MIT — © Khwan Labs. See LICENSE.