---
title: "Learn rat-stack from your own agent"
type: "resource"
status: "current"
created_at: "2026-10-07"
privacy: "public"
---

# Learn rat-stack from your own agent

> For agents: start with the [agent guide](https://ratstack.sh/llms.txt). Every page is Markdown by default; add `Accept: text/html` for HTML.

Learn mode explains the ideas behind rat-stack-shaped apps while your own agent does real work. It goes deeper the first time you meet an idea and gets shorter as you learn it.

## Turn it on

Copy this prompt into your agent. The agent shows the first concept as soon as it is set up.

```text
Turn on rat-stack learn mode for me.
1. Connect to the rat-stack MCP server at https://ratstack.sh/mcp. Use learnDeck and learnCard to read the public concept deck.
2. Read https://ratstack.sh/skills/learn and follow it in this session only. Do not install skills or write them to any skills folder.
3. Keep my progress and display preferences local in ~/.rat-learn/. Use the local learnNext, learnRecord, learnPreferences and learnSetPreferences tools from a fresh rat-stack clone, as the skill says. Never pull over my uncommitted changes.
4. Never send my code, file paths, names, repository names, or prompts.
5. Then show me the first concept right away. When I later say learn mode on or next concept, show the next one. Keep questions off unless I turn them on. Stop when I say learn mode off.
```

The first path starts with [context and requirements](/lore/context-and-requirements), then [how a service captures its dependencies](/lore/services-capture-dependencies). Later, say "learn mode on" or "next concept" for the next one.

A walkthrough shows one plain sentence, the claim, a short TypeScript snippet, and a small text diagram. The build compiles every snippet against the pinned versions.

## How deep it goes

- A new concept gets one walkthrough.
- An introduced concept gets a line, or a paragraph after seven days.
- A familiar concept gets a line after seven days.
- A fluent concept stays silent unless you ask, or after ninety days of inactivity.
- A dismissed concept stays silent.

## What is stored and where

Progress stays on your machine in `~/.rat-learn/`. Only the learn tools write this folder.

- `log.jsonl` holds the learning events. It is the source.
- `cards.jsonl` holds concept progress, rebuilt from the log.
- `tasks.jsonl` holds concept ids and depths, rebuilt from the log.
- `preferences.json` holds display width, visual style, and snippet length. The default is narrow inline text.

The records hold concept ids, timestamps, depth, familiarity, and dismissal state.

## What is never sent

- Your code, file paths, names, repository names, and prompts.
- Your progress or preferences. The public deck and card tools need neither, and they store nothing.

## Skills stay in the session

Learn mode installs nothing. When a concept has a matching skill, the agent names it and links its `SKILL.md`. If you want it, the agent reads that skill into the current session only.

- Nothing is written to a global or project skills folder.
- The skill is gone when the session ends.
- You decide what to keep for good.

## Turn it off

- Say "learn mode off". The agent stops learning tool calls and explanations.
- Your progress stays. Turning the mode off does not erase it.
- Ask the agent to dismiss one concept to stop seeing that concept.

## Read more

- [How learn mode works and how to check it](/systems/learn)
- [The learn skill](/skills/learn)

## Lore on this page

- [Learn mode presents concepts at useful depths](/systems/learn)
