Cairn

Cairn es un almacén de solo añadido de hechos tipados. Un agente afirma un hecho en una sesión y lo recuerda, con un veredicto de frescura, al comienzo de la siguiente.

Los hechos persisten en SQLite. El escritorio es opcional. El trabajo ocurre en JSON y MCP.

Instalación

npx cairn init --project
npx cairn dev

init --project crea .cairn/cairn.db, conecta Cursor (.cursor/mcp.json) y conecta Pi (.mcp.json).

Instalación global sin archivo de proyecto:

npx cairn init

Related MCP server: identity-storage-mcp

Comandos

Contrato del agente

Envía JSON a POST /api/cairn o llama a las herramientas MCP cairn_recall y cairn_request.

Cada escritura lleva una idempotencyKey. Repite la misma clave y cuerpo después de un fallo y Cairn devuelve el resultado original sin escribir dos veces.

Recall devuelve freshness y assurance en cada creencia. Ramifica según response.kind. Los rechazos incluyen error.remedy.kind.

Ejemplo de afirmación

curl -s http://127.0.0.1:4721/api/cairn \
  -H 'content-type: application/json' \
  -d '{
    "kind": "assert",
    "idempotencyKey": "s-021-deploy",
    "onConflict": "supersede",
    "draft": {
      "entity": "repo:acme/checkout",
      "attribute": "deploy.command",
      "value": { "kind": "text", "text": "bin/ship --env staging" },
      "provenance": {
        "kind": "observed",
        "command": "cat Makefile && bin/ship --help",
        "session": "s-021"
      },
      "validity": { "kind": "until-superseded" }
    }
  }'

Plugins de arnés

Cursor. Después de cairn init --project, .cursor/mcp.json incluye un servidor cairn que ejecuta npx cairn mcp.

Pi. El mismo init escribe .mcp.json para Pi y otros clientes MCP. Pi lee .mcp.json e importaciones de host como cursor.

Escritorio y lienzo

Abre Escritorio (/) para la tabla de creencias y la consola de la API del agente. Abre Lienzo (/canvas) para ver cada agente o sesión como un contenedor arrastrable con los hechos que contribuyeron.

Los agentes se agrupan por provenance.by para hechos contados y por provenance.session para hechos observados o inferidos. Arrastra los pods para organizar el tablero; el diseño persiste en .cairn/canvas.json.

Publicar e instalar desde npm

npm publish
npx cairn init --project
npx cairn dev

El tarball publicado incluye el escritorio completo, el lienzo, la API, la CLI y el servidor MCP. Requiere Node 20+.

Desarrollo

npm install
npm test
npm run dev

La ruta de la base de datos se resuelve a ./.cairn/cairn.db cuando ese directorio existe; de lo contrario, ~/.cairn/cairn.db. Sobrescribe con CAIRN_HOME o CAIRN_DB_PATH.

Tráiler de lanzamiento (Remotion)

Un tráiler de producto de ~30s para X vive en cairn-trailer/. Previsualiza con npm run dev dentro de esa carpeta, o renderiza:

cd cairn-trailer
npx remotion render CairnTrailer out/cairn-v0.4-trailer.mp4

Consulta cairn-trailer/x-post-draft.md para el texto sugerido de la publicación.

Lo que Cairn rechaza

Valores JSON de forma libre. Búsqueda semántica. Editar hechos en el lugar. Esperar a un humano a mitad de la solicitud.