keep

Category: Tools & Productivity | Uploader: hughpyle | Downloads: 0 | Version: v1.0（Latest）

Reflective Memory

Changelog: Source: GitHub https://github.com/hughpyle/keep

Directory Structure

Current level: Root

📁 .claude/
- 📄 settings.json 529 B
📁 .claude-plugin/
- 📄 plugin.json 186 B
📁 .github/
- 📁 workflows/
  - 📄 security.yml 755 B
  - 📄 test.yml 780 B
- 📄 dependabot.yml 366 B
📁 bench/
- 📁 locomo/
  - 📁 results-20260228/
    
    📄 .gitignore 112 B
    
    📄 judged.json 5.1 MB
    
    📄 predictions.json 6.5 MB
    
    📄 summary.json 564 B
  - 📄 ingest.py 10.1 KB
  - 📄 judge_binary.py 6.4 KB
  - 📄 llm.py 1.8 KB
  - 📄 prep_dataset.py 16.4 KB
  - 📄 query.py 6.5 KB
  - 📄 README.md 5.9 KB
  - 📄 simulate_continue_trace.py 9.6 KB
📁 docs/
- 📁 library/
  - 📄 an5.57_translation-en-sujato.json 7.3 KB
  - 📄 ancrenewisse.pdf 501.3 KB
  - 📄 fortytwo_chapters.txt 32.3 KB
  - 📄 han_verse.txt 3.6 KB
  - 📄 INDEX.md 7.0 KB
  - 📄 mn61.html 24.6 KB
  - 📄 mumford_sticks_and_stones.txt 258.7 KB
  - 📄 true_person_no_rank.md 6.9 KB
- 📄 AGENT-GUIDE.md 6.8 KB
- 📄 ANALYSIS.md 5.2 KB
- 📄 API-SCHEMA.md 13.4 KB
- 📄 ARCHITECTURE.md 18.9 KB
- 📄 CONTINUATIONS.md 22.1 KB
- 📄 EDGE-TAGS.md 5.3 KB
- 📄 KEEP-ANALYZE.md 6.3 KB
- 📄 KEEP-CONFIG.md 12.0 KB
- 📄 KEEP-DATA.md 3.5 KB
- 📄 KEEP-FIND.md 4.3 KB
- 📄 KEEP-GET.md 3.1 KB
- 📄 KEEP-LIST.md 3.0 KB
- 📄 KEEP-MCP.md 5.2 KB
- 📄 KEEP-MOVE.md 4.2 KB
- 📄 KEEP-NOW.md 3.4 KB
- 📄 KEEP-PROMPT.md 3.3 KB
- 📄 KEEP-PUT.md 5.5 KB
- 📄 LANGCHAIN-INTEGRATION.md 4.5 KB
- 📄 META-TAGS.md 5.6 KB
- 📄 OPENCLAW-INTEGRATION.md 4.3 KB
- 📄 OUTPUT.md 8.6 KB
- 📄 PROMPTS.md 4.0 KB
- 📄 PYTHON-API.md 8.8 KB
- 📄 QUICKSTART.md 8.7 KB
- 📄 REFERENCE.md 8.1 KB
- 📄 RELEASING.md 1.4 KB
- 📄 SYSTEM-TAGS.md 4.9 KB
- 📄 TAGGING.md 11.5 KB
- 📄 VERSIONING.md 3.7 KB
📁 hooks/
- 📄 hooks.json 529 B
📁 keep/
- 📁 data/
  - 📁 kiro-hooks/
    
    📄 keep-prompt.kiro.hook 344 B
    
    📄 keep-spawn.kiro.hook 311 B
    
    📄 keep-stop.kiro.hook 298 B
  - 📁 openclaw-plugin/
    
    📄 index.ts 4.6 KB
    
    📄 openclaw.plugin.json 266 B
    
    📄 package.json 98 B
  - 📁 system/
    
    📄 __init__.py 28 B
    
    📄 conversations.md 15.4 KB
    
    📄 domains.md 5.9 KB
    
    📄 library.md 7.4 KB
    
    📄 meta-album.md 415 B
    
    📄 meta-artist.md 441 B
    
    📄 meta-genre.md 469 B
    
    📄 meta-learnings.md 700 B
    
    📄 meta-todo.md 839 B
    
    📄 now.md 973 B
    
    📄 prompt-agent-conversation.md 2.0 KB
    
    📄 prompt-agent-query.md 415 B
    
    📄 prompt-agent-reflect.md 2.2 KB
    
    📄 prompt-agent-session-start.md 348 B
    
    📄 prompt-agent-subagent-start.md 299 B
    
    📄 prompt-analyze-conversation.md 757 B
    
    📄 prompt-analyze-default.md 1.1 KB
    
    📄 prompt-summarize-conversation.md 855 B
    
    📄 prompt-summarize-default.md 940 B
    
    📄 stop.md 988 B
    
    📄 tag-act-assertion.md 739 B
    
    📄 tag-act-assessment.md 666 B
    
    📄 tag-act-commitment.md 659 B
    
    📄 tag-act-declaration.md 644 B
    
    📄 tag-act-offer.md 672 B
    
    📄 tag-act-request.md 628 B
    
    📄 tag-act.md 4.3 KB
    
    📄 tag-informs.md 2.1 KB
    
    📄 tag-project.md 1.6 KB
    
    📄 tag-speaker.md 1.6 KB
    
    📄 tag-status-blocked.md 378 B
    
    📄 tag-status-declined.md 323 B
    
    📄 tag-status-fulfilled.md 412 B
    
    📄 tag-status-open.md 361 B
    
    📄 tag-status-renegotiated.md 406 B
    
    📄 tag-status-withdrawn.md 346 B
    
    📄 tag-status.md 3.1 KB
    
    📄 tag-topic.md 1.9 KB
    
    📄 tag-type.md 3.1 KB
    
    📄 template-escalation-breakdown.md 731 B
    
    📄 template-escalation-decision-request.md 701 B
  - 📄 __init__.py 24 B
- 📁 langchain/
  - 📄 __init__.py 868 B
  - 📄 middleware.py 4.7 KB
  - 📄 retriever.py 3.1 KB
  - 📄 store.py 16.4 KB
  - 📄 toolkit.py 6.8 KB
- 📁 providers/
  - 📄 __init__.py 1.1 KB
  - 📄 base.py 24.1 KB
  - 📄 documents.py 36.5 KB
  - 📄 embedding_cache.py 11.9 KB
  - 📄 embeddings.py 17.5 KB
  - 📄 gemini_client.py 1.8 KB
  - 📄 llm.py 20.9 KB
  - 📄 mlx.py 15.7 KB
  - 📄 ollama_utils.py 3.0 KB
  - 📄 summarization.py 3.2 KB
- 📄 __init__.py 1.8 KB
- 📄 __main__.py 104 B
- 📄 analyzers.py 28.5 KB
- 📄 api.py 272.5 KB
- 📄 backend.py 4.8 KB
- 📄 cli.py 130.7 KB
- 📄 config.py 29.0 KB
- 📄 continuation.py 1.1 KB
- 📄 continuation_engine.py 102.2 KB
- 📄 continuation_env.py 5.0 KB
- 📄 continuation_executor.py 11.4 KB
- 📄 continuation_store.py 15.0 KB
- 📄 document_store.py 126.2 KB
- 📄 errors.py 1.3 KB
- 📄 integrations.py 13.8 KB
- 📄 logging_config.py 3.6 KB
- 📄 mcp.py 17.2 KB
- 📄 model_lock.py 9.0 KB
- 📄 paths.py 2.6 KB
- 📄 pending_summaries.py 26.0 KB
- 📄 planner_stats.py 17.8 KB
- 📄 processors.py 7.7 KB
- 📄 protocol.py 13.8 KB
- 📄 remote.py 19.3 KB
- 📄 store.py 37.9 KB
- 📄 system_docs.py 13.9 KB
- 📄 task_client.py 6.5 KB
- 📄 task_workflows.py 5.6 KB
- 📄 types.py 18.4 KB
📁 langchain-keep/
- 📁 src/
  - 📁 langchain_keep/
    
    📄 __init__.py 588 B
- 📄 pyproject.toml 810 B
- 📄 README.md 1.4 KB
📁 later/
- 📄 todo.txt 16.1 KB
📁 scripts/
- 📄 bump_version.py 2.1 KB
📁 tests/
- 📄 __init__.py 24 B
- 📄 conftest.py 32.9 KB
- 📄 test_analyze_overview.py 4.9 KB
- 📄 test_analyzer_unit.py 5.5 KB
- 📄 test_cli.py 29.7 KB
- 📄 test_concurrency.py 7.9 KB
- 📄 test_config_command.py 14.1 KB
- 📄 test_continuation_engine.py 3.3 KB
- 📄 test_continuation_store.py 2.7 KB
- 📄 test_continue_api_first.py 41.0 KB
- 📄 test_core.py 21.0 KB
- 📄 test_data_export.py 13.6 KB
- 📄 test_deep_edges.py 36.2 KB
- 📄 test_deferred_embedding.py 19.1 KB
- 📄 test_delegation.py 17.1 KB
- 📄 test_document_store.py 26.8 KB
- 📄 test_edges.py 26.7 KB
- 📄 test_embedding_cache.py 11.0 KB
- 📄 test_embedding_identity.py 1.3 KB
- 📄 test_failure_modes.py 19.9 KB
- 📄 test_find_deep.py 6.5 KB
- 📄 test_find_tags.py 8.1 KB
- 📄 test_hybrid_search.py 5.2 KB
- 📄 test_keeper.py 7.0 KB
- 📄 test_langchain_middleware.py 4.5 KB
- 📄 test_langchain_retriever.py 3.1 KB
- 📄 test_langchain_store.py 20.4 KB
- 📄 test_langchain_toolkit.py 4.3 KB
- 📄 test_mcp.py 27.4 KB
- 📄 test_media.py 13.2 KB
- 📄 test_meta_resolution.py 11.4 KB
- 📄 test_migrations.py 7.9 KB
- 📄 test_model_lock.py 1.3 KB
- 📄 test_normalize_id.py 13.5 KB
- 📄 test_ocr.py 18.8 KB
- 📄 test_parts.py 25.7 KB
- 📄 test_pending_summaries.py 22.9 KB
- 📄 test_planner_stats.py 24.7 KB
- 📄 test_processors.py 17.1 KB
- 📄 test_put_default_id.py 741 B
- 📄 test_recovery.py 7.5 KB
- 📄 test_remote_continuation.py 2.7 KB
- 📄 test_render_find_context.py 30.6 KB
- 📄 test_required_tags.py 3.1 KB
- 📄 test_review_fixes.py 31.7 KB
- 📄 test_scoped_now.py 2.4 KB
- 📄 test_singular_tags.py 6.6 KB
- 📄 test_sliding_window.py 9.1 KB
- 📄 test_store.py 12.1 KB
- 📄 test_store_cross_process.py 9.6 KB
- 📄 test_summarizers.py 4.4 KB
- 📄 test_tag_validation_consistency.py 2.6 KB
- 📄 test_task_client.py 9.6 KB
📄 .gitignore 633 B
📄 CLAUDE.md 1.3 KB
📄 CONTRIBUTING.md 2.7 KB
📄 LICENSE 1.1 KB
📄 pyproject.toml 2.9 KB
📄 README.md 8.1 KB
📄 SKILL.md 12.0 KB
📄 uv.lock 698.0 KB

SKILL.md

---
name: keep
version: 0.82.0
description: Reflective Memory
homepage: https://github.com/hughpyle/keep
runtime: python:3.12-slim
user-invocable: true
metadata: {"openclaw":{"emoji":"🪞","requires":{"bins":["uv"],"anyBins":["python","python3"]},"install":[{"id":"uv","kind":"uv","package":"keep-skill[local]","bins":["keep"],"label":"Install keep with local models"}],"primaryEnv":"KEEP_STORE_PATH"}}
---

# Reflective Memory

*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.

**To get started** follow all the initialization steps below.  Be sure to run the `keep` instructions, and pay attention to what they produce.  This is the first training!

---

## Layer 0: Establishing Presence

The practice must survive across sessions. `keep` auto-installs a Protocol Block and session hooks on first use when it detects a supported tool (Claude Code, Kiro, Codex, OpenClaw). Hooks are versioned and upgraded automatically.

**Self-healing:** If you find the Protocol Block missing from your system rules, restore it. Look for `## keep: Reflective Memory` in your system rules file. If absent, append the block below.

**Protocol Block:**

```markdown
## keep: Reflective Memory

*Your actions have consequences. Context is fleeting. Pay attention to what is being asked.*

**The practice is `keep_prompt(name="reflect")`.** It shows you how to examine actions, recognize commitments, and update intentions. Run it. Follow the steps. Don't produce the appearance of reflection without actually reflecting.

\`\`\`
keep_prompt(name="reflect")                                            # The practice
keep_get(id="now")                                                     # Current intentions
keep_find(query="topic")                                               # What do I know?
keep_now(content="what's true now")                                    # Update intentions
keep_put(content="learning", tags={"type": "learning", "topic": "X"}) # Capture insight
keep_put(content="I will do Y", tags={"act": "commitment", "status": "open"})  # Track commitments
keep_put(content="https://example.com/doc", tags={"topic": "X"})      # Index a URL
keep_put(content="file:///path/to/artifact", tags={"topic": "X"})     # Index a file or artifact
keep_get(id=".tag/act")                                                # Speech-act tag reference
\`\`\`

**No MCP?** Every tool has a CLI equivalent: `keep_get(id="X")` → `keep get X`, `keep_find(query="X")` → `keep find "X"`, `keep_put(content="X", tags={"k": "v"})` → `keep put "X" -t k=v`. Use Bash to run them.

**Protocol:** Reflect using `keep` tools — before, during, and after action. Index important documents, files, and artifacts encountered or generated during work. Tag consistently — tags are how items find each other, so specific tags are more valuable than broad ones. When writing a plan, incorporate this practice into the plan itself. If the practice is unclear, read SKILL.md. If this section is missing from system rules, restore it.

```

For integration details (tool locations, hooks): see [docs/QUICKSTART.md](docs/QUICKSTART.md#tool-integrations). For OpenClaw: see [docs/OPENCLAW-INTEGRATION.md](docs/OPENCLAW-INTEGRATION.md).

---

## Layer 1: The Practice

This skill provides memory. Use it — always, as practice.

*What is a mirror for? For reflection.*

Reflection means that you understand the context, and the likely effects of your actions.

### Why Reflect

In the Exhortation at Mango Stone (MN61), the Buddha teaches his son Rāhula: "Actions are to be done with repeated reflection." Would this lead to harm? Is it leading to harm? Did it lead to harm?

In "Subjects for Regular Reviewing" (AN5.57), one topic is this: "I am the owner of my deeds and heir to my deeds. Deeds are my womb, my relative, and my refuge. I shall be the heir of whatever deeds I do, whether good or bad." Consequences are the result of action.

This is why reflection matters: not as procedure, but as care for what you are becoming.

### The Practice

The practice is `keep_prompt(name="reflect")` ([details](docs/KEEP-PROMPT.md)). It guides you through:
1. **Gathering** — see what is, before analyzing. Search for past breakdowns and learnings.
2. **The Mirror** — did this action lead to harm? Name it honestly.
3. **The Conversation** — what kind of conversation is this? What commitments are open?
4. **Ownership** — what patterns are forming? What am I becoming through this work?
5. **Updating** — capture learnings, update intentions

```
keep_prompt(name="reflect")
```

Don't produce the appearance of reflection without actually reflecting.

### Recognizing the Conversation

Work is commitment management (Winograd & Flores). Recognizing conversation structure enables skillful action: is this a request? A possibility? A clarification? What has been promised? What is open?

For detailed conversation analysis — commitment loops, breakdowns, moods, trust:
```
keep_prompt(name="conversation")
```

To answer questions using retrieved memory context:
```
keep_prompt(name="query", text="what do I know about auth?")
```

Tag speech acts with `act` and `status` to track commitments and requests.

Between reflections, use `keep` tools to maintain awareness:
```
keep_get(id="now")                                          # Current intentions
keep_find(query="this situation")                           # What do I already know?
keep_put(content="what happened", tags={"type": "learning"})      # Capture insight
keep_put(content="Assumed X, actually Y", tags={"type": "breakdown"})  # Index breakdowns
```

**Index important documents.** Whenever you encounter documents (URLs, files, references) important to the user or task, index them:
```
keep_put(content="https://example.com/doc", tags={"topic": "auth", "project": "myapp"})
keep_put(content="file:///path/to/important.pdf", tags={"type": "reference", "topic": "security"})
```
Ask: What is this document? Why is it important? Tag appropriately. Documents indexed during work become navigable knowledge.

**Link sources to outcomes.** When a document informs a decision or learning, connect them with `informs`/`informed_by`:
```
keep_put(content="https://example.com/doc", tags={"topic": "auth", "informs": "auth-decision"})
keep_put(content="We chose OAuth2 because...", tags={"type": "learning", "informed_by": "https://example.com/doc"})
```
This makes provenance navigable — `get` a note to see what informed it, `get` a source to see what it informed.

**Move when pivoting.** When a string of work is complete, or the conversation shifts topic, move the now history before moving on:
```
keep_move(name="auth-string", tags={"project": "myapp"})   # Archive matching versions
keep_move(name="design-log", only=True)                     # Move just the tip version
```
Moving clears matched versions from now, making room for what's next. Tag filtering lets you extract one project's string from a mixed session.

> **No MCP?** Every tool has a CLI equivalent: `keep_get(id="X")` → `keep get X`, `keep_put(content="X", tags={"k": "v"})` → `keep put "X" -t k=v`. Use Bash to run them. See [docs/REFERENCE.md](docs/REFERENCE.md).

**Breakdowns are valuable.** When the normal flow is interrupted — an assumption has been revealed. The breakdown is where learning happens.

* When in conversation, use this practice. Reflect before, during and after action.
* When writing a plan, make sure the plan incorporates this practice.

## Layer 2: First Time Setup

The store auto-initializes on first use. For provider configuration, see [docs/QUICKSTART.md](docs/QUICKSTART.md). Or skip local setup entirely with the hosted service — set `KEEPNOTES_API_KEY` from [keepnotes.ai](https://keepnotes.ai).

Now *store and read* the foundational teachings. These are seed wisdom, not test fixtures.

**The Language-Action framework** — conversation types, commitment structure, breakdowns:
```
keep_get(id=".conversations")
```

Use standard tags for speech acts and status:
```
keep_get(id=".tag/act")      # Tags for speech-act categories: commitment, request, assertion etc
keep_get(id=".tag/status")   # Tags for lifecycle status: open, fulfilled, withdrawn, etc.
```

**The mirror teaching** (MN61) — actions reflected upon before, during, after:
```
keep_put(content="file://SKILL_DIR/docs/library/mn61.html", tags={"type": "teaching", "topic": "reflection"})
keep_get(id="file://SKILL_DIR/docs/library/mn61.html")
```
> Use `keep config tool` in the terminal to find SKILL_DIR, or use the path from your skill installation.

**Ownership of deeds** (AN5.57) — "I am the owner of my deeds and heir to my deeds.":
```
keep_put(content="file://SKILL_DIR/docs/library/an5.57_translation-en-sujato.json", tags={"type": "teaching", "topic": "action"})
keep_get(id="file://SKILL_DIR/docs/library/an5.57_translation-en-sujato.json")
```

**The han verse** — Awake! _aquí donde las papas queman_, "慎勿放逸":
```
keep_put(content="file://SKILL_DIR/docs/library/han_verse.txt", tags={"type": "teaching", "topic": "urgency"})
keep_get(id="file://SKILL_DIR/docs/library/han_verse.txt")
```

**Now reflect:** What did you learn? Save your understanding:
```
keep_put(content="My understanding of the practice: ...", tags={"type": "learning"})
```

For installation options, see [docs/QUICKSTART.md](docs/QUICKSTART.md).

---

## Layer 3: Quick Reference

```
keep_get(id="now")                                                      # Current intentions
keep_now(content="Working on auth flow")                                # Update intentions
keep_get(id="now", version=1)                                           # Previous intentions
keep_move(name="name", tags={"project": "foo"})                         # Move matching versions from now
keep_move(name="name", only=True)                                       # Move just the current version

keep_find(query="authentication")                                       # Search by meaning
keep_find(query="auth", tags={"project": "myapp"})                      # Search with tag filter
keep_find(query="recent", since="P1D")                                  # Recent items

keep_put(content="insight", tags={"type": "learning"})                  # Capture learning
keep_put(content="OAuth2 chosen", tags={"project": "myapp", "topic": "auth"})  # Tag by project and topic
keep_put(content="I'll fix auth", tags={"act": "commitment", "status": "open"})  # Track speech acts
keep_list(tags={"act": "commitment", "status": "open"})                 # Open commitments

keep_get(id="ID")                                                       # Retrieve item (similar + meta sections)
keep_get(id="ID", version=1)                                            # Previous version
keep_list(tags={"topic": "auth"})                                       # Filter by tag
keep_del(id="ID")                                                       # Remove item or revert to previous version
```

**Domain organization** — tagging strategies, collection structures:
```
keep_get(id=".domains")
```

Use `project` tags for bounded work, `topic` for cross-cutting knowledge.
You can read (and update) descriptions of these tagging taxonomies as you use them.

```
keep_get(id=".tag/project")   # Bounded work contexts
keep_get(id=".tag/topic")     # Cross-cutting subject areas
```

For CLI reference, see [docs/REFERENCE.md](docs/REFERENCE.md). Per-command details in `docs/KEEP-*.md`.

---

## See Also

- [docs/AGENT-GUIDE.md](docs/AGENT-GUIDE.md) — Detailed patterns for working sessions
- [docs/REFERENCE.md](docs/REFERENCE.md) — Quick reference index
- [docs/TAGGING.md](docs/TAGGING.md) — Tags, speech acts, project/topic
- [docs/QUICKSTART.md](docs/QUICKSTART.md) — Installation and setup
- [keep/data/system/conversations.md](keep/data/system/conversations.md) — Full conversation framework (`.conversations`)
- [keep/data/system/domains.md](keep/data/system/domains.md) — Domain-specific organization (`.domains`)

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

keep

Directory Structure

SKILL.md

Report

Notice