# Learnings

The project's episodic memory: a timestamped ledger of rules paid for with real outages...

- Repository: https://github.com/kortix-ai/suna (20345 stars)
- Category: Design
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add kortix-ai/suna --skill learnings -g -a claude-code -y`
Codex: `npx skills add kortix-ai/suna --skill learnings -g -a codex -y`
Cursor: `npx skills add kortix-ai/suna --skill learnings -g -a cursor -y`
Gemini CLI: `npx skills add kortix-ai/suna --skill learnings -g -a gemini-cli -y`

## Description

The project's episodic memory: a timestamped ledger of rules paid for with real outages and near-misses, one entry per incident, plus `work/`: the plans, designs and open thoughts behind planned or parked work. Load WHENEVER you write or review a DB migration or schema change, touch deploy/release workflows (.github/workflows/deploy-*, promote.yml, vercel config), plan a promote/release, respond to a prod incident, or when another skill references a learning. ALSO load after resolving any incident or near-miss: it must leave a new ledger entry in the same session. ALSO load before picking up or planning a larger initiative (goals, workflows, the factory as a state machine), and to persist a plan or open thought so someone else can continue it.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Project learnings: the episodic ledger

Every rule this repository paid for with downtime or a near-miss is one entry in a
timestamped, append-only ledger. The ledger is the full history, in the order it was
learned.

| Path | What it is |
| --- | --- |
| `MEMORY.md` | The index. One line per entry, newest first: recorded time (UTC) and the rule. Generated. |
| `entries/<YYYY-MM-DDTHHMMSSZ>-<slug>.md` | One entry. The filename timestamp is when it was recorded. |
| `scripts/new-entry.sh` | Starts a new entry stamped with the current UTC time and rebuilds the index. |
| `scripts/index.sh [--check]` | Rebuilds `MEMORY.md` from `entries/`, or fails if it is stale. |
| `work/<topic>/` | Plans, designs and open thoughts for planned, in-flight or parked work. Living documents, not part of the ledger. Index and rules: `work/README.md`. |

Entries recorded before 2026-09-25 were split out of the old single-file register. Their
`recorded` time is the commit that first wrote them (`commit` in the frontmatter).

## Recall: before you touch a surface

1. Search the index and the full text for the surface you are about to change:
   ```bash
   grep -i '<keyword>' .agents/skills/learnings/MEMORY.md
   grep -ril '<keyword>' .agents/skills/learnings/entries/
   ```
   Use the words of the surface: `migration`, `CONCURRENTLY`, `deploy-dev`, `promote`,
   `wake`, `Stop`, `gateway`, `preview`, the file or route name.
2. Read every matching entry in full. Obey its **Rule**, and keep its **Enforcement** green.

Done when every entry that names the surface you touch has been read.

## Record: after an incident or near-miss resolves

Record in the same session. An incident that leaves no entry is not finished.

The rest: https://github.com/kortix-ai/suna/blob/HEAD/.agents/skills/learnings/SKILL.md