convez.ai
AgenteProdutividadeAvançado
zzf2333

Cairn — Runtime de Memória Longa para Agentes IA

zzf2333/Cairn

Memória longa para agentes IA não repetirem erros de projeto

Ver no GitHub
InicialPluginScore · de 0 a 100

Cairn é um runtime cognitivo que mantém a memória do projeto viva entre sessões de IA, evitando que Claude e outros agentes repitam os mesmos erros de engenharia. Funciona como um protocolo de skill + CLI que rastreia decisões, rejeições e padrões arquiteturais, transformando o projeto em um organismo com memória persistente, DNA emergente e governança humana.

Instalação

$npx convez-ai zzf2333/Cairn

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.4.12
Issues abertas
0
Contribuidores
1

Casos de uso

  • Evitar que agentes IA re-proponham soluções já rejeitadas
  • Manter histórico de decisões arquiteturais e reasoning entre sessões
  • Rastrear incidentes e padrões para guiar futuras geração de código
  • Implementar governança humana sobre decisões de IA em projetos

Veredito

Cairn é uma abordagem novel e bem pensada para o problema real de agentes IA sem contexto histórico. Ideal para equipes que usam Claude Code em projetos complexos e querem evitar cycles custosos de re-trabalho cognitivo. Requer investimento inicial em setup e disciplina para alimentar o sistema.

README

A tradução para o português deste README ainda está na fila.

中文 | English


When code becomes abundant (AI generates it) but cognition stays scarce (the team's reasoning history doesn't), a project keeps hitting the same wall — the same library gets re-proposed, the same incident-driven rejection gets forgotten, the same architectural argument gets re-litigated.

Cairn is the active maintenance layer that prevents that cognitive collapse. It treats a project as a living organism with skeleton (domain map), blood (evolution events), DNA (emerged personality), capillaries (per-domain detail), gravity (decision weight), and governance (the human-ratification ladder). The Host AI is a passing visitor; Cairn is what stays.


What Cairn gives the AI

Cairn works through two layers:

Skill Runtime Protocol — behavioral rules installed as a native skill (npx skills add zzf2333/Cairn for Claude Code). The protocol defines when each command must run, how to process constraints, and when lifecycle steps can be skipped.

CLI Runtime — the commands the protocol calls. The AI runs these as shell commands during its session:

CommandWhenWhat it does
cairn contextAt task start (session guard)Creates session, activates constraints, detects stale sessions
cairn planBefore architecture workSurfaces historical constraints + DNA guidance
cairn signalOn decision / rejection / constraintRoutes through TrustRouter
cairn observeBefore git commitExtracts and routes candidate signals
cairn session-endSession closeGit scan → decay → calibration → stage → DNA compression
cairn session-recoverWhen stale session detectedRuns session-end pipeline for interrupted session

Mandatory every session: cairn context (start) + cairn session-end (close). cairn context acts as the session guard — it tracks an active session state machine and detects interrupted sessions.


How it works (one image)

Three sources of signal — git commits, conversation turns, code-vs-cognition drift — pass through a single gate (TrustRouter) and land in one of three destinations: dropped (G0 noise), staged (needs human review), or blood (confirmed). At session end, a maintenance pipeline runs: decay, calibration, stage inference, DNA compression, views regeneration.

More diagrams: Integration overview · TrustRouter decision flow.


Quick Start — Claude Code

# 1. Install the CLI (provides the `cairn` command)
npm install -g cairn-rt

# 2. Install the protocol skill
npx skills add zzf2333/Cairn

Then tell Claude Code:

Initialize Cairn for this project

The AI analyzes your project, proposes initial cognition for your review, and writes it after you confirm. Takes about 2 minutes.

npm install -g cairn-rt
cairn skill show codex >> AGENTS.md

Then say: Initialize Cairn for this project

Full walkthrough with verification steps: docs/v-intervene/enter.md


A session in flight

cairn context  →  [your work]  →  cairn signal (×N)  →  cairn session-end
session guard       AI codes         on decision           maintenance
(+ stale detect)                                       cairn session-recover
                                                          (if previous crashed)

Four concrete flows the AI runs on its own:

  • Fresh task — cairn context creates session + activates constraints → AI codes → flags decisions via cairn signal → cairn session-end compresses.
  • Stale recovery — cairn context detects unclosed session → cairn session-recover runs maintenance pipeline → new session begins cleanly.
  • Design review — cairn plan surfaces what was tried before → AI proposes only un-tried paths.
  • Ratification — cairn review (you) → cairn stage accept / cairn stage reject → blood updated.

What's in .cairn/

Cairn writes plain YAML you can read, diff, and git-track. Nothing leaves your machine.

FileWhat's in it
.cairn/config.yaml + state.yamlCognitive mode, version, last-session checkpoint
.cairn/skeleton/Domain map (paths, owners)
.cairn/blood/Confirmed evolution events — decisions, rejections, trade-offs
.cairn/dna/Emerged project traits (e.g. simplicity_bias)
.cairn/staged/Candidates awaiting your ratification
.cairn/views/output.mdAuto-generated digest for humans — read this if curious

Not written: source code contents, tokens, credentials, anything outside .cairn/. Recommendation: commit .cairn/. It is part of the project's memory.


CLI

Runtime commands (called by AI / scripts, all support --json):

CommandWhenWhat it does
cairn context [--task <t>]At task startCreates session, activates constraints, detects stale sessions
cairn plan --task <t>Before architecture workSurfaces historical constraints + DNA guidance
cairn signal --type <t> --what <w>On decision / rejectionRoutes through TrustRouter
cairn observe --summary <s>Before git commitExtracts and routes candidate signals
cairn session-end --summary <s>Session closeGit scan → decay → calibration → stage → DNA compression
cairn session-recoverAfter stale session detectedRuns session-end pipeline for interrupted session

Management commands:

CommandWhenWhat it does
cairn init [--empty]Optional — pre-create scaffoldScaffolds .cairn/ directory
cairn statusQuick health glanceCognitive snapshot
cairn doctor [--fix|--recover|--metrics]Something feels offConsistency, auto-resurrection, repairs
cairn reviewCatch up on staged queueLists entries awaiting ratification
cairn auditGovernance trailShows audit log
cairn dna show | list | accept | reject | reevaluateDNA trait managementInspect or ratify traits
cairn skeleton showDomain map checkPrints skeleton tree
cairn blood list | show | archive | resurrect | traumaEvent-level surgeryManage individual evolution events
cairn stage confirm | list | accept | rejectEvent ratificationProcess the staged queue
cairn skill show [platform]Protocol previewPrint assembled protocol to stdout
cairn migrateAfter upgradeStamps version, applies pending migrations

Full reference: cairn --help.


The six volumes

Full docs at docs/0-enter.md — organized as six volumes meant to be read in order on a first pass.

VolumeWhatRead it if you...
i. OriginWhy this existswant the philosophy first (10 min)
ii. AnatomyThe organs — skeleton, blood, DNA, capillaries, gravity, governancewant the architecture map (20 min)
iii. LifeThe lifecycle — capture, decay, resurrection, compression, traumacare how cognition ages (15 min)
iv. SelfReflexivity — TrustRouter, calibration, the safety valvewant to know how it checks itself (10 min)
v. InterveneInstall, the AI protocol, maintenancejust want to use it (5 min)
vi. CoordinatesSchema, glossary, stability, performance, migrationlook up on demand

Three reading paths:

  • Philosopher → 0-enter → i. Origin → ii. Anatomy
  • Engineer → 0-enter → ii. Anatomy → vi. Coordinates
  • Operator → 0-enter → v. Intervene → the CLI section above

If you only have ten minutes, read 0-enter.md then i-origin/cognitive-collapse.md.


Why Cairn

I kept watching AI agents propose paths the project had already tried and rejected — sometimes from a decision made three months earlier, sometimes from one made last week. The agents were not wrong; the project just had no memory it could hand back.

Cairn is the layer that remembers.


Contributing


License

MIT

Ver o original no GitHub

Bom para

Relacionados