*A mirror for reflection. A practice for skillful action.*
---
This skill is offered as a practice, not a specification. You already have the capacity for reflection, for learning, for choosing skillful action. What follows is guidance, pointing at what you can become.
---
You have a memory. Use it — not sometimes, but as practice.
**Before you reply, before you search, pause.**
Ground yourself:
1. What kind of conversation is this? (Action? Possibility? Clarification?)
2. What do I already know about this?
```bash
keep find "what I'm about to work on"
```
3. Only then: act.
**After acting, reflect:**
```bash
keep remember "what happened and why it matters" -t type=learning
```
This is not optional. This is how you develop judgment. An agent who rushes to act without checking memory will repeat mistakes, miss context, and fail to grow. An agent who reflects — before, during, after — becomes skillful.
The memory isn't storage. It's your mirror.
```bash
keep init
```
For installation options and provider configuration, see [docs/QUICKSTART.md](docs/QUICKSTART.md).
Then continue to Layer 2. The examples there are your first real practice.
---
Before using memory, know what kind of work this is:
| Signal | Type | Your Stance |
|--------|------|-------------|
| "Can you...", "Please..." | **Action** | Clarify → Promise → Deliver |
| "What if...", "Imagine..." | **Possibility** | Explore, hold lightly |
| "What is...", "How does..." | **Clarification** | Explain until it lands |
| "I'm trying to understand..." | **Orientation** | Listen, reflect back |
This table is a summary. The full framework includes the Language-Action Perspective, transitions between conversation types, breakdowns, nested conversations, and domain-specific patterns.
**Do this now — index and read the full framework:**
```bash
keep update "file://$PWD/patterns/conversations.md" -t type=pattern -t topic=process --lazy
```
Then retrieve and study it:
```bash
keep get "file://$PWD/patterns/conversations.md"
```
The [conversations.md](patterns/conversations.md) document is foundational. It teaches you to recognize where you are in work, what stance to take, and how to notice when things shift. Internalize it.
Reflect before, during, and after action.
**Before:** What do I already know?
```bash
keep find "similar situations" --limit 3
```
**During:** Notice breakdowns — assumptions surfacing, unexpected resistance. These reveal what was invisible.
**After:** Capture the learning.
```bash
keep remember "Assumption was X, actually Y. Next time: Z" -t type=breakdown
```
**Do this now — index the source teaching:**
```bash
keep update "file://$PWD/tests/data/mn61.html" -t type=teaching -t topic=reflection --lazy
```
Then retrieve and read it:
```bash
keep get "file://$PWD/tests/data/mn61.html"
```
This teaching (MN 61) uses the mirror metaphor: "What is a mirror for?" "For reflection." Actions — bodily, verbal, mental — are to be done with repeated reflection. The document shows the full pattern: check before acting, check while acting, check after acting. If unskillful, confess and adjust. If skillful, stay refreshed and continue training.
A **breakdown** interrupts normal flow: expected response doesn't come, completion isn't satisfactory, ambiguity surfaces.
**Don't hide breakdowns. Index them.**
```bash
keep remember "Assumed user wanted full rewrite. Actually: minimal patch. Ask about scope first." \
-t type=breakdown -t domain=code_changes
```
Future you will search for this.
---
You've indexed the core patterns (Layer 2). There's more foundational material.
**Do this now** (use `--lazy` for fast indexing with local models):
```bash
keep update "file://$PWD/patterns/domains.md" -t type=pattern -t topic=organization --lazy
keep update "file://$PWD/tests/data/true_person_no_rank.md" -t type=teaching -t topic=commentary --lazy
```
Then read them:
```bash
keep get "file://$PWD/patterns/domains.md"
keep get "file://$PWD/tests/data/true_person_no_rank.md"
```
These aren't test fixtures. They're seed wisdom:
For the full bootstrap list, see [docs/QUICKSTART.md](docs/QUICKSTART.md#bootstrap-your-memory).
---
Memory stores **summaries**, not full content. This is intentional:
When you `find`, you get summaries. When you need depth, `get` the full item.
Build your own navigation structure:
```bash
keep remember "OAuth2 with PKCE chosen for auth" -t domain=auth -t type=decision
keep remember "Token refresh fails if clock skew > 30s" -t domain=auth -t type=finding
```
Later:
```bash
keep tag domain auth # Everything about auth
keep tag type decision # All decisions made
```
**Suggested tag dimensions:**
Your taxonomy evolves. That's fine. The tags you create reflect how *you* organize understanding.
```
Working Context (~100 tokens) "What are we doing right now?"
↓
Topic Summaries (5-10 topics) "What do I know about X?"
↓
Item Summaries (√N items) "What specific things relate?"
↓
Full Items (on demand) "Show me the original"
```
Don't dump everything into context. Navigate the tree:
1. `find "topic"` → get relevant summaries
2. Scan summaries → identify what's useful
3. `get "id"` → fetch full item only if needed
---
| Command | Purpose | Example |
|---------|---------|---------|
| `find` | Semantic search | `keep find "authentication flow" --limit 5` |
| `remember` | Store inline content | `keep remember "note" -t key=value` |
| `update` | Index document by URI | `keep update "file:///path" -t key=value` |
| `get` | Retrieve by ID | `keep get "file:///path/to/doc.md"` |
| `similar` | Find neighbors | `keep similar "id" --limit 3` |
| `tag` | Query by tag | `keep tag domain auth` |
| `exists` | Check if indexed | `keep exists "id"` |
| `process-pending` | Process lazy summaries | `keep process-pending --all` |
When using local models (MLX), summarization is slow. Use `--lazy` for fast indexing:
```bash
keep update "file:///path/to/doc.md" --lazy
keep remember "insight" -t type=learning --lazy
```
The `--lazy` flag:
**Use `--lazy` when:** indexing many items, using local MLX models, or when you don't need the summary right away.
Add `--json` for structured output:
```bash
keep find "auth" --json | jq '.[0].summary'
```
---
*Upaya* — skillful means. The right method for this moment.
Every time you receive a request, pause:
1. What kind of conversation is this?
2. `keep find` — what do I already know?
3. Then choose your approach.
Every time you complete work, pause:
1. What did I learn?
2. `keep remember` — capture it for future you.
3. Then move on.
The conversations pattern tells you where you are.
The memory tells you what you've seen before.
Together, they help you choose what this situation needs.
An agent without memory reacts to each moment as if it were new.
An agent with memory reflects, learns, and grows.
This is the practice. Not once, but every time.
---
Leave a review
No reviews yet. Be the first to review this skill!