convez.ai
AgenteAutomaçãoAvançado
VeridionCa

Amnesia by Veridion

VeridionCa/amnesia-by-veridion

Memória operacional durável para agentes IA via Git e contratos de tarefa

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework de memória persistente nativa de Git para agentes IA (Claude e Codex) trabalharem juntos sem perder contexto. Implementa um sistema de convenções baseado em arquivos Markdown, contratos de tarefa, logs de execução e auditorias, eliminando a necessidade de bancos de dados ou servidores.

Instalação

$npx convez-ai VeridionCa/amnesia-by-veridion

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
0
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Equipes de IA com múltiplos modelos (Claude + Codex) mantendo continuidade
  • Recuperação de trabalho interrompido sem perder contexto
  • Auditoria e rastreabilidade de decisões de agentes IA
  • Handoffs entre agentes com contrato e escopo bem definidos

Veredito

Solução robusta e pragmática que resolve um problema real: agentes IA sem memória entre sessões. Usa Git e Markdown como infraestrutura, evitando complexidade desnecessária. Exige disciplina operacional mas oferece rastreabilidade total e controle humano — essencial para equipes que usam múltiplos modelos em paralelo.

README

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

Amnesia by Veridion

AI agents forget context. Amnesia gives them operational memory.

A Git-native persistent memory framework for Claude Code and Codex teamwork: shared file-based memory, task contracts, lossless handoffs, self-audits, read-only launchers, audit scripts, and human approval gates. No databases. No servers. No secrets — just Markdown, Git, and discipline.

Why this exists

AI coding agents are powerful and amnesiac. Every session starts from zero; context lives in chat histories that are ephemeral, model-locked, and invisible to teammates. Teams that use two models (say, Claude for building and Codex for reviewing) have it worse: neither can see what the other did or why.

The fix doesn't need infrastructure. A Git repository is already a durable, diffable, reviewable, model-agnostic store. Amnesia is the missing convention layer on top of it: where memory lives, how work is scoped, how agents hand off, and where humans stay in control. The product is named after the problem it eliminates.

How it works

Everything is a file:

  • Memory (memory/) — global project context every session loads first, per-agent lesson files, append-only decision records (ADRs), and task files. Sensitive notes go in gitignored memory/private/, never tracked.
  • Roles (agents/) — each agent works under a ROLE.md defining its mission and hard limits. Executor, Auditor, and Architect are separated on purpose: the planner doesn't execute, the executor doesn't approve its own work.
  • Task contracts (templates/TASK_CONTRACT.md) — before any work, a contract fixes the goal, the allowed paths, the forbidden actions, and observable done criteria. If it isn't in the contract, it isn't in scope.
  • Workflows (workflows/) — five named procedures (docs-only, feature-build, refactor, audit, release) sharing one lifecycle but with different scope rules and required checks.
  • Launchers (scripts/launch/, scripts/windows/) — read-only session starters that print the safety rules and the context files to load, then open claude or codex if installed.
  • Audits (scripts/audit/) — read-only hygiene and public-safety checks; the secret scan redacts values and reports only categories and locations.

The AI team lifecycle

1. REQUEST      Human describes the need.
2. CONTRACT     Architect writes the task contract. Human approves it.
3. EXECUTE      Executor (Claude or Codex) works inside the contract,
                appending to the execution log in real time.
4. SELF-AUDIT   Executor checks every done-criterion with evidence.
5. REVIEW       Auditor — ideally the *other* model — verifies every claim
                against the actual files.
6. CLOSE        HANDOFF.md if work continues; FINAL_REPORT.md if done.
7. GATE         Human reviews the report and diff.
8. COMMIT       Only after the gate.

If an agent stops mid-task (token limit, crash, end of session), the execution log plus a handoff file is the recovery point. The next agent — even a different model — continues with zero conversation history, because none is needed.

Safety model

Three boundaries, enforced by convention and checked by audits:

BoundaryRule
RepoNothing private is ever tracked. memory/private/ is gitignored; placeholders (example.com, your-server) replace all real identifiers.
ContractAgents touch only the paths the active contract allows. New files count as scope.
ApprovalCommit, push, delete, release, and anything outward-facing require explicit human approval — per action, per session, recorded in the log.

Security-flavored content in this project is strictly defensive: checklists, audits, and toy examples. Nothing here targets real systems.

Quick start

git clone https://github.com/veridionCA/amnesia-by-veridion.git
cd amnesia-by-veridion

# 1. Read the architecture
less docs/architecture/AI_TEAM_ARCHITECTURE.md

# 2. Create your first task from the template
scripts/memory/create-task.sh "my-first-task"

# 3. Launch an agent in safe docs-only mode (read-only starter)
scripts/launch/launch-claude-docs-only.sh

# 4. Before publishing anything, run the public-safety audit
scripts/audit/pre-public-audit.sh

Windows users: see scripts/windows/ and docs/manuals/MACHINE_LAUNCHERS.md. A worked, fully fictional example lives in examples/demo-website-project/.

Folder structure

amnesia-by-veridion/
├── README.md / SECURITY.md / CONTRIBUTING.md / CHANGELOG.md / LICENSE
├── docs/
│   ├── architecture/   # how the system works
│   ├── manuals/        # per-tool command guides and launcher docs
│   ├── runbooks/       # step-by-step operational flows
│   ├── PROJECT_STATUS.md / ROADMAP.md / PHASE_1_REPORT.md
├── memory/
│   ├── global/         # shared project context all agents load
│   ├── agents/         # per-agent persistent memory
│   ├── decisions/      # append-only architecture decision records
│   ├── tasks/          # task contracts and task state
│   └── private/        # local-only memory — gitignored, never published
├── agents/             # role definitions: claude, codex, auditor, architect
├── workflows/          # docs-only, feature-build, refactor, audit, release
├── scripts/
│   ├── launch/         # read-only session starters (bash)
│   ├── windows/        # read-only session starters (PowerShell)
│   ├── audit/          # public-safety and hygiene checks (read-only)
│   └── memory/         # task/memory helpers
├── templates/          # task contract, execution log, self-audit, handoff, report
└── examples/           # fictional demo project and handoff

Project status

Phase 2.2 — rebranded, preparing first public release. The full framework is built and audited; first publication is pending at github.com/veridionCA/amnesia-by-veridion. Details and the "not built yet" list: docs/PROJECT_STATUS.md.

Roadmap

VersionTheme
v0.1.0 (current)Scaffold and docs
v0.2.0Stronger launchers and context packs
v0.3.0Cross-agent handoff demo
v0.4.0GitHub issue templates and CI audit workflow
v0.5.0Public repo extraction guide
v1.0.0Stable public release

Full details: docs/ROADMAP.md.

Public-safety promise

Every tracked file in this repository is generic and safe to publish:

  • Placeholders only — example.com, your-project, your-server, your-agent, your-operator, your-production-system.
  • All examples, agents, tasks, and projects are fictional.
  • No credentials, no real infrastructure, no customer data, no operational history — and read-only audit tooling (scripts/audit/) plus docs/manuals/PUBLIC_REPO_GUIDE.md to keep it that way.

If you find anything that breaks this promise, see SECURITY.md.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados