---
slug: "lessons-pi"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/lee259/lessons@main/README.md"
repo: "https://github.com/lee259/lessons"
source_file: "README.md"
branch: "main"
---
# Lessons

**English** | [简体中文](https://github.com/lee259/lessons/blob/HEAD/README.zh-CN.md)

**Verified engineering lessons for coding agents** — not chat soft-memory.

After a real file change + passing test/build/lint/typecheck, Lessons captures a
distilled L2 Lesson as reviewable Markdown in your repo.

**Status:** early preview `0.1.1` on npm · OpenCode + Pi · MIT  
**Packages:** `@lessons/core` · `@lessons/opencode` · `@lessons/pi`  
**Requires:** Node `>=20` · OpenCode `>=1.18` · Pi coding-agent `0.81` (Pi path needs Node `>=22.19`)

[Install](#install) · [First 3 minutes](#first-3-minutes) · [Docs](#docs) · [Contributing](#contributing)

---

## Why Lessons

| Typical agent memory | Lessons |
| --- | --- |
| Remembers chat / preferences | Remembers **verified** engineering lessons |
| Soft write bar | File change + task-shaped verification + L2 Lesson |
| Often private DB | Git-reviewable Markdown under `docs/lessons/` |

```text
change → verify → distill Lesson → Markdown Memory → next task reads it
```

## Install

Lessons ships two host adapters on the same Markdown core. OpenCode is the
primary dogfood path (one-command installer + host smoke). Pi shares compose /
seed / Quiet Capture through `@lessons/pi`.

### OpenCode

```bash
npx -y -p @lessons/opencode lessons-opencode install
```

Restart OpenCode, then run `/lessons-status`.

<details>
<summary>What the OpenCode installer does</summary>

1. Adds `"plugin": ["@lessons/opencode"]` to `~/.config/opencode/opencode.json(c)`
2. Writes `/lessons-seed` and `/lessons-status` under `~/.config/opencode/commands/`
3. Writes `~/.config/opencode/plugins/lessons.js` shim for local symlink installs
4. With `--local`, symlinks built packages into OpenCode `node_modules/@lessons/`

</details>

### Pi

```bash
pi install npm:@lessons/pi
```

Restart Pi (or `/reload`), then run `/lessons-status`. Details:
[`packages/pi/README.md`](https://github.com/lee259/lessons/blob/HEAD/packages/pi/README.md).

### Local monorepo (contributors)

```bash
git clone https://github.com/lee259/lessons.git
cd lessons
pnpm install && pnpm build
node packages/opencode/dist/cli.js install --local   # OpenCode
pi install ./packages/pi                             # Pi
```

## First 3 minutes

1. `/init` → project `AGENTS.md` (OpenCode native; **not** Lessons; skip on Pi)
2. `/lessons-seed` → narrative `docs/lessons/CONTEXT.md` ([ADR-003](https://github.com/lee259/lessons/blob/HEAD/docs/lessons/adr/003-context-seed-ownership.md))
3. After a verified task, Agent calls `lessons_finish_episode` with a short reusable summary

`/lessons-seed` ≠ `/init`. Soft-close does **not** Capture template summaries.

- OpenCode tools + prompts: [OpenCode usage](https://github.com/lee259/lessons/blob/HEAD/docs/en/opencode-usage.md)
- Pi surfaces: [`packages/pi/README.md`](https://github.com/lee259/lessons/blob/HEAD/packages/pi/README.md)

## What gets captured

Needs **all** of:

- concrete project file change
- task-shaped verification (`test` / `build` / `lint` / `typecheck` / …)
- reusable L2 Lesson (not “updated file X”, not raw tool stdout)

`pwd` / `ls` / `git status` never Capture. Chat-only claims never Capture.

## Preview scope

| In | Out |
| --- | --- |
| OpenCode plugin + Pi extension + Markdown Memories | Broader multi-host platform |
| Shared core compose / seed / Capture | Pi one-command install + host-smoke parity |
| Lesson-first Capture + CONTEXT seed | In-repo code-graph engine |
| Soft-fail host isolation | Production support / LTS guarantees |

## Docs

| Doc | Purpose |
| --- | --- |
| [docs/en/design-overview.md](https://github.com/lee259/lessons/blob/HEAD/docs/en/design-overview.md) | Short product overview |
| [docs/en/opencode-usage.md](https://github.com/lee259/lessons/blob/HEAD/docs/en/opencode-usage.md) | Tools + end-to-end OpenCode flows |
| [packages/pi/README.md](https://github.com/lee259/lessons/blob/HEAD/packages/pi/README.md) | Pi extension install + surfaces |
| [docs/lessons/adr/](https://github.com/lee259/lessons/tree/HEAD/docs/lessons/adr/) | Binding architecture decisions |
| [CONTRIBUTING.md](https://github.com/lee259/lessons/blob/HEAD/CONTRIBUTING.md) | Dev setup + PR checks |
| [SECURITY.md](https://github.com/lee259/lessons/blob/HEAD/SECURITY.md) | Reporting + redaction notes |
| [CHANGELOG.md](https://github.com/lee259/lessons/blob/HEAD/CHANGELOG.md) | Release notes |
| [README.zh-CN.md](https://github.com/lee259/lessons/blob/HEAD/README.zh-CN.md) | Chinese homepage |

## Contributing

```bash
pnpm install && pnpm verify
```

Optional OpenCode host checks (`OPENCODE_BIN` required): see [CONTRIBUTING.md](https://github.com/lee259/lessons/blob/HEAD/CONTRIBUTING.md).

## License

MIT — [LICENSE](https://github.com/lee259/lessons/tree/HEAD/LICENSE).