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 GitHubCairn é 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/Cairn1 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
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:
| Command | When | What it does |
|---|---|---|
cairn context | At task start (session guard) | Creates session, activates constraints, detects stale sessions |
cairn plan | Before architecture work | Surfaces historical constraints + DNA guidance |
cairn signal | On decision / rejection / constraint | Routes through TrustRouter |
cairn observe | Before git commit | Extracts and routes candidate signals |
cairn session-end | Session close | Git scan → decay → calibration → stage → DNA compression |
cairn session-recover | When stale session detected | Runs 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 contextcreates session + activates constraints → AI codes → flags decisions viacairn signal→cairn session-endcompresses. - Stale recovery —
cairn contextdetects unclosed session →cairn session-recoverruns maintenance pipeline → new session begins cleanly. - Design review —
cairn plansurfaces 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.
| File | What's in it |
|---|---|
.cairn/config.yaml + state.yaml | Cognitive 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.md | Auto-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):
| Command | When | What it does |
|---|---|---|
cairn context [--task <t>] | At task start | Creates session, activates constraints, detects stale sessions |
cairn plan --task <t> | Before architecture work | Surfaces historical constraints + DNA guidance |
cairn signal --type <t> --what <w> | On decision / rejection | Routes through TrustRouter |
cairn observe --summary <s> | Before git commit | Extracts and routes candidate signals |
cairn session-end --summary <s> | Session close | Git scan → decay → calibration → stage → DNA compression |
cairn session-recover | After stale session detected | Runs session-end pipeline for interrupted session |
Management commands:
| Command | When | What it does |
|---|---|---|
cairn init [--empty] | Optional — pre-create scaffold | Scaffolds .cairn/ directory |
cairn status | Quick health glance | Cognitive snapshot |
cairn doctor [--fix|--recover|--metrics] | Something feels off | Consistency, auto-resurrection, repairs |
cairn review | Catch up on staged queue | Lists entries awaiting ratification |
cairn audit | Governance trail | Shows audit log |
cairn dna show | list | accept | reject | reevaluate | DNA trait management | Inspect or ratify traits |
cairn skeleton show | Domain map check | Prints skeleton tree |
cairn blood list | show | archive | resurrect | trauma | Event-level surgery | Manage individual evolution events |
cairn stage confirm | list | accept | reject | Event ratification | Process the staged queue |
cairn skill show [platform] | Protocol preview | Print assembled protocol to stdout |
cairn migrate | After upgrade | Stamps 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.
| Volume | What | Read it if you... |
|---|---|---|
| i. Origin | Why this exists | want the philosophy first (10 min) |
| ii. Anatomy | The organs — skeleton, blood, DNA, capillaries, gravity, governance | want the architecture map (20 min) |
| iii. Life | The lifecycle — capture, decay, resurrection, compression, trauma | care how cognition ages (15 min) |
| iv. Self | Reflexivity — TrustRouter, calibration, the safety valve | want to know how it checks itself (10 min) |
| v. Intervene | Install, the AI protocol, maintenance | just want to use it (5 min) |
| vi. Coordinates | Schema, glossary, stability, performance, migration | look 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
- Issues + PRs: https://github.com/zzf2333/Cairn
- Protocol:
SKILL.md - Release checklist (contributor-facing, internal): see
docs/internal/in repo
License
MIT