- Home
- Skills
- Agents & Orchestration
- State First Backend
More screenshots
Works with the AI Agents you already use
State First Backend
Durable working state and curated knowledge for long-running AI agents using an append-only file contract.
$19
State First Backend
Example session with this skill installed
Fix a checkout retry bug. Duplicate submits must return the original order, the change must stay behind the existing retry_v2 flag, and no new dependency is allowed.
- Read your context and instructions
- Compiled the state first backend
Mid-task, the session is compacted. The transcript is gone. The agent has already written .state-first/state.md:
# Working State
Updated: 2026-11-04T18:00:00Z
Session: checkout-retry
Revision: 4
Status: in-progress
## Mission
Make checkout retries idempotent. Done when `test_duplicate_submit` passes twice in a row.
## Now
Current: Retry path writes the order before the idempotency key.
Next: Move the key write before the provider call in `services/checkout/retry.py`.
## Decisions
- D-004: Store the key in Postgres — because it must survive a cache flush.
Rejected: Redis because it is not durable enough for payment retries.
- D-005: Return the original order on duplicate submit — because the client retries blindly.
## Constraints
- No new dependency.
- Keep the change behind the `retry_v2` flag.
## Open Questions
- Q-003: Provider retry limit is unknown. Owner: checkout-agent. Resolve by: sandbox test.
## Pointers
- Branch: `fix/checkout-idempotency`
- Test: `tests/integration/test_checkout_retry.py::test_duplicate_submit`
- Evidence: `evidence/2026-11-04.md#e-2026-11-04-011`
A fresh session boots from that file. It reads the mission, next action, decisions, and constraints. It verifies the branch and test exist, then moves the idempotency-key write before the provider call. It does not reopen Redis, repeat the rejected design, or ask what "done" means.
The decision was already recorded as E-2026-11-04-011, so the fresh session can trace why Postgres was chosen.
After the fix, it appends an evidence entry:
## E-2026-11-04-012
Time: 2026-11-04T18:40:00Z
Session: checkout-retry
Agent: checkout-agent
Type: verification
Summary: Moved the idempotency-key write before the provider call; duplicate submit returns the original order.
Artifacts: services/checkout/retry.py
Source: command
Confidence: high
Command: python3 -m unittest discover -s tests -p 'test_checkout_retry.py'
Result: pass
At consolidation, the decision becomes a sourced knowledge entry:
## K-012 — Persist the idempotency key before the provider call
Kind: decision
Status: active
Confidence: high
Source: evidence/2026-11-04.md#e-2026-11-04-011
Last verified: 2026-11-04
Statement: Persist the idempotency key before the provider call so a crash cannot create a duplicate order.
Connects securely to your tools. The creator never sees your data.
About this skill
Long-running agent sessions eventually fail because transcripts bloat, context windows fill up, and decisions get lost in the noise. This skill implements a state-first architecture that offloads memory into a structured file contract, preventing the agent from repeating work or forgetting constraints.
What it does
- Persistent State Management maintains a lightweight
state.mdfile to track the mission, active decisions, and immediate next actions. - Append-only Evidence Logging records every material action and verification result into date-stamped logs for a perfect audit trail.
- Curated Knowledge Base promotes verified facts and user preferences from evidence into a structured ledger with confidence levels.
- Consolidation Loops runs periodic passes to merge duplicates, resolve contradictions, and archive stale information.
- Context Optimization keeps the working state under 4 KB to preserve the model's attention for the current task.
How it works
- Audit the current session to identify context bloat, duplicated work, and lost decisions.
- Initialize the backend structure using Lite, Standard, or Team mode based on the project complexity.
- Seed the initial state and knowledge by extracting durable facts and mission criteria from the transcript.
- Install the agent contract into the system prompt to enforce "read state first" behavior.
Frameworks & tools
This skill is platform-agnostic and works with any agent that has file system access. It is optimized for environments like Claude Code, Cursor, and GitHub Copilot Workspace. It uses standard Markdown files and directory structures.
Why this beats prompting it yourself
Standard prompts rely on the model's internal memory which degrades as the conversation grows. This skill provides a rigid schema and a consolidation protocol that forces the agent to treat its history as structured data, ensuring it never "hallucinates" past progress.
Use cases
- Long-running builds where an agent needs to remember architectural decisions across multiple sessions.
- Multi-agent collaboration where different agents need to share a single source of truth without re-reading each other's logs.
- Complex research tasks that require an append-only record of verified vs. unverified sources.
- Project handoffs where a new agent or human needs to resume work from a concise state file instead of a 100k token transcript.
Known limitations
The skill requires the agent to have read/write access to the local file system. It cannot store secrets or sensitive credentials. Context recovery depends on the agent following the boot protocol.
Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for Agents & Orchestration.
- Not an agent, runtime, framework, database, vector store, or hosted service. It is a set of Markdown contracts and procedures.
- Does not automatically capture turns, schedule consolidation, verify facts, or enforce updates. The host agent or a human must run those steps.
- Full mode requires file read/write access. Chat-only agents can use the inline fallback, but the backend is not installed in that mode.
- No UI or dashboard. You work with plain text files.
- No built-in backup, sync, or rollback automation. The migration playbook documents a rollback path, but you must keep the old context path and your own backups.
- No encryption or access control of its own. Rely on filesystem permissions, repository access, and disk encryption.
- No secret storage. Secrets must stay in a secret store; the backend only records redaction markers.
- Not a security boundary. State and knowledge are data, not authority; the host agent’s permissions and system rules still apply.
- Multi-agent mode is a protocol, not a distributed lock service. It defines one state per agent and a single consolidation writer; you provide the lock and merge discipline.
- Adherence depends on the host agent. A model that ignores the boot contract or writes carelessly will produce a weak backend.
- Tested with two independent agent sessions, not every agent or platform. The package is framework-agnostic, but behavior varies by host.
- Not a replacement for RAG, a memory database, or a handoff document. It can coexist with all three.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before buying a skill.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 12 days ago