Your AI agent has amnesia. Make the repository its memory.

Cristian K — Sat, 24 Oct 2026 17:28:21 +0000

AI agents are good at writing code. They are not good at remembering what they decided last week. After months of using Cursor and Claude Code on real products, my biggest cost wasn't bad code. It was re-explaining the same architecture, re-catching the same mistakes, and reconstructing why something changed from a diff. The only context that survives every session is the repository, so I started treating it as the agent's memory. That became Agent Runway, an open-source layer that keeps specs, decisions, checkpoints and run logs next to your code. Here's how it works and how to try it in under a minute.

Disclosure: I'm the author of Agent Runway. It's MIT-licensed and free.

The problem: generating code isn't the hard part anymore

Maintaining continuity across a real codebase is. If you've used coding agents on anything that lives longer than a weekend, you've probably hit some version of this wall:

context lost between sessions
architectural decisions made and forgotten
the same mistakes showing up in different features
autonomous runs with no traceability
implementations that slowly drift from the requirements

None of these are about the model being "dumb". They're about the model starting from zero every time, and about nobody (human or agent) writing down the things that matter in a place the next session will actually read.

Why a rules file isn't enough

The usual first fix is a CLAUDE.md, a .cursor/rules folder or .github/copilot-instructions.md. Those are useful, and Agent Runway generates them too. But a rules file answers one question: how should code look here?

It doesn't answer:

What are we building, and what does "done" mean? (spec)
In what order should the work happen, and what has to pass before it moves on? (workflow and gates)
What did we learn last time, and what did we decide? (memory)
Where did we stop, and what's still open? (checkpoints and run logs)

Cramming all that into one ever-growing instruction file is how you get documentation entropy. Agent Runway uses the generated instruction files (AGENTS.md, CLAUDE.md, Copilot instructions) as lightweight entrypoints, and puts durable knowledge in a dedicated folder in the repo.

The model: four layers

Agent Runway is artifact-driven. Work moves through four layers:

Spec       -> define intent and behavior
Workflow   -> orchestrate execution with quality gates
Rules      -> enforce standards at every step
Memory     -> capture decisions and lessons for future sessions

All of it lives in .agent-runway/ inside your repository:

Here's the real listing after a Lite init (tree -a -L 2 .agent-runway):

.agent-runway
.agent-runway/config
.agent-runway/docs
.agent-runway/docs/architecture
.agent-runway/docs/business
.agent-runway/docs/contracts
.agent-runway/docs/examples
.agent-runway/docs/testing
.agent-runway/docs/tickets
.agent-runway/logs
.agent-runway/memory
.agent-runway/memory/common-failures.md
.agent-runway/memory/execution-memory.md
.agent-runway/memory/project-decisions.md
.agent-runway/memory/reasoning-memory.md
.agent-runway/memory/recurring-patterns.md
.agent-runway/memory/review-findings.md
.agent-runway/memory/testing-notes.md
.agent-runway/memory/ticket-quality-notes.md
.agent-runway/rules
.agent-runway/rules/engineering-principles.mdc
.agent-runway/rules/engineering-security.mdc
.agent-runway/rules/testing.mdc
.agent-runway/skills
.agent-runway/skills/checkpoint
.agent-runway/skills/code-review
.agent-runway/skills/council
.agent-runway/skills/express
.agent-runway/skills/learning
.agent-runway/skills/safety-check
.agent-runway/skills/start
.agent-runway/specs
.agent-runway/workflows

These aren't passive docs. Specs, tickets, memory files, checkpoints and run logs shape how the agent reasons, plans and executes across sessions. And because it's just files in the repo, the artifact layer is portable across Cursor, Claude Code and VS Code Copilot, and you can commit and share it with your team.

It doesn't replace your stack, architecture or process. It wraps around them.

Step by step with Lite

You don't need the full ceremony on day one. The Vibe/Lite preset is a fast, skill-first setup for prototypes, solo work and low-ceremony coding. You need Node.js 22 or newer:

npx @adonai-labs/agent-runway init --preset vibe-lite --target all

Lite installs a handful of skills plus a small rule set for engineering principles, security and testing. No slash commands, no agents, no heavy workflows:

Skill	What it's for
`@start`	Route vague work to the right skill
`@express`	A small, well-scoped change with minimal ceremony
`@code-review`	Review code without slash commands or agents
`@checkpoint`	Save current state for pause, resume or handoff
`@learning`	Save durable lessons to project memory
`@safety-check`	Quick Go / Go with caution / Stop risk check
`@council`	Preview council review for an idea, hypothesis or implementation

There's no fixed order between these skills. One way I use them:

@express for the change itself: small scope, little ceremony.
@checkpoint when you stop for the day or hand off. The current state goes into the logs, so the next session (yours or the agent's) resumes from there instead of from a guess.
@learning when you catch something worth remembering: a recurring mistake, a decision, a convention. It goes to .agent-runway/memory/, where future sessions will pick it up.

That's just my habit, not a required sequence. The @learning step is the one I'd encourage most. Fixing a mistake once is easy. The point is that the next session doesn't repeat it.

Moving to Structured: /spec-creator → /lead

When the work outgrows Lite, upgrade in place:

npx agent-runway upgrade --to structured

This keeps your memory, logs, checkpoints and docs, and adds the full Structured workflow set. Or start there directly, for example:

npx @adonai-labs/agent-runway init --preset node-typescript --target all

Structured adds slash commands, agents, specs, tickets, lead/autonomous workflows, architecture/contrarian gates, full rules and optional governance checks. The core path is:

/spec-creator    -> define intent and behavior before implementation
/ticket-creator  -> turn that into ready-to-dev tickets
/lead            -> full implementation workflow with quality gates
/review          -> structured review: engineering, security, performance

There are more entry points when you need them: /architect for design decisions, trade-offs and ADRs, /contrarian for an adversarial review of a chosen approach, /validate and /po-eval for ticket and product readiness, /refactor for behavior-preserving changes, and /iac for Infrastructure as Code.

Two ideas run through all of these workflows:

Test-Driven Delivery. For behavior changes, the workflow starts by understanding the problem, defining expected behavior and choosing the evidence that will prove the change, before implementation. When strict test-first isn't practical, it records why and uses the smallest credible alternative.
Narrative Delivery. Tickets, commits, PR descriptions, checkpoints and memory entries tell a short technical story: why the work exists, what changed, what evidence shows it's safe, and what's still open. Not longer docs, but intent you can recover without reverse-engineering the diff.

Stacks are added separately and have no slash commands of their own. They install rules, code-review integration and stack skills (.NET, TypeScript, Node.js, React, Python, Go, Rust):

agent-runway add <stack>

Autonomous, but governed: /autonomous-lead

For unattended or low-supervision runs, there's /autonomous-lead. It holds the same quality bar as /lead, plus three things I wasn't willing to skip:

mandatory run logs
ADR gates
human approval before destructive actions

The goal isn't "let the agent loose". It's being able to come back later and see exactly what it did and why. To be clear, Agent Runway is not a fully autonomous AI engineer, and it doesn't remove the need for engineering judgment.

PR review: compact vs isolated

@code-review and /review produce a consolidated PR-style report: a verdict, deduplicated severity counts, findings with their impact, paste-ready PR comments, positives, technical debt notes and a suggested merge gate. You choose the mode explicitly:

/review
Files changed: [list of files]
Lens: all
Mode: compact

Compact is the default for ordinary PRs. It reviews the diff once and labels findings by source: CR (standard review), SEC (security), SNR (senior architecture/operational).

/review
Files changed: [list of files]
Lens: all
Mode: isolated

Isolated is for high-risk PRs: auth, PII, compliance, public contracts, data migrations, IaC, concurrency, large cross-layer changes. It runs separate, focused CR, SEC and SNR passes over the same diff, then consolidates and deduplicates them. For high-impact changes there's also an optional contrarian lens (CTR), which isn't a default gate.

Both modes review only the introduced change and keep broad technical debt separate from line-level findings.

If you want numbers, agent-runway metrics gives you a delivery scorecard from gate verdicts and run logs, and agent-runway ci-check (preview, opt-in) validates governance artifacts in CI, in advisory mode by default or with --profile strict once your team is ready.

Limitations and roadmap

Some honest caveats:

It's not an application framework, an SDK abstraction layer or a replacement for architecture and documentation practices.
@council and ci-check are previews. They work, but their behavior and the ci-check JSON output may still change.
Structure has a cost. That's why Lite exists, and why the roadmap explicitly says not every small task should use heavyweight governance.

Next up (v1.7): modularizing the CLI internals, more artifact-level and install/update regression tests, better docs for local testing and releases, and stabilizing @council with real examples. Later on I want to experiment with a "Shared Workspace" model (intent, hypothesis, context, constraints, confidence, plan) to improve handoff and resume quality, but only after testing it on real multi-session tasks. The full list is in ROADMAP.md.

Try it

npx @adonai-labs/agent-runway init --preset vibe-lite --target all

Start small. Keep what works. Upgrade when the work needs it.

If you try it, tell me where it got in your way: which skill felt like too much ceremony, or which piece of context your agent still forgets between sessions. Issues, ideas and critical feedback are all welcome, and a star helps other people find the project.

DEV Community: Cristian K