Skip to content

AGENT-GUIDE.md

Latest commit

 

History

History
205 lines (138 loc) · 8.31 KB

AGENT-GUIDE.md

File metadata and controls

205 lines (138 loc) · 8.31 KB

Reflective Memory — Agent Guide

Patterns for using the reflective memory store effectively in working sessions.

For the practice (why and when), see ../SKILL.md. For CLI reference, see REFERENCE.md. For the output format, see OUTPUT.md.

Note: Examples below use keep_flow (the primary MCP interface). CLI equivalents (keep flow put -p content=X, etc.) are available for hooks and terminal use — see REFERENCE.md.

The Practice

This guide assumes familiarity with the reflective practice in SKILL.md. The key points:

Reflect before acting: Check your current work context and intentions.

  • What kind of conversation is this? (Action? Possibility? Clarification?)
  • What do I already know?
keep_flow(state="get", params={"item_id": "now"})
keep_flow(state="query-resolve", params={"query": "this situation"})

keep_flow(state="get", ...) returns the requested note first, including its tags, with any relevant attached context such as similar notes, meta sections, parts, linked notes, and version navigation. Read it as "show me this note and what surrounds it", not as a bare exact fetch.

While acting: Is this leading to harm? If yes: give it up.

Reflect after acting: What happened? What did I learn?

keep_flow(state="put", params={"content": "what I learned", "tags": {"kind": "learning"}})

Periodically: Run a full structured reflection (details):

keep_prompt(name="reflect")

This cycle — reflect, act, reflect — is the mirror teaching. Memory isn't storage; it's how you develop skillful judgment.

Working Session Pattern

Use the nowdoc as a scratchpad to track where you are in the work. This isn't enforced structure — it's a convention that helps you (and future agents) maintain perspective.

// 1. Starting work — check context and intentions
keep_flow(state="get", params={"item_id": "now"})

// 2. Update context as work evolves
keep_flow(state="put", params={"id": "now", "content": "Diagnosing flaky test in auth module", "tags": {"project": "myapp", "topic": "testing"}})
keep_flow(state="put", params={"id": "now", "content": "Found timing issue", "tags": {"project": "myapp"}})

// 3. Record learnings
keep_flow(state="put", params={"content": "Flaky timing fix: mock time instead of real assertions", "tags": {"topic": "testing", "kind": "learning"}})

Key insight: The store remembers across sessions; working memory doesn't. When you resume, read context first. All updates create version history automatically.

Agent Handoff

Starting a session:

keep_flow(state="get", params={"item_id": "now"})
keep_flow(state="query-resolve", params={"query": "recent work", "since": "P1D"})

Ending a session:

keep_flow(state="put", params={"id": "now", "content": "Completed OAuth2 flow. Token refresh working. Next: add tests.", "tags": {"topic": "auth"}})
keep_flow(state="move", params={"name": "auth-string", "tags": {"project": "myapp"}})

Strings

As you work, now accumulates a string of versions — a trace of how intentions evolved. The move flow lets you name and archive that string, making room for what's next.

Snapshot before pivoting. When the conversation shifts topic:

keep_flow(state="move", params={"name": "auth-string", "tags": {"project": "myapp"}})
keep_flow(state="put", params={"id": "now", "content": "Starting on database migration"})

Incremental archival. Move to the same name repeatedly — versions append:

keep_flow(state="move", params={"name": "design-log", "tags": {"project": "myapp"}})

Tag-filtered extraction. When a session mixes projects:

keep_flow(state="move", params={"name": "frontend-work", "tags": {"project": "frontend"}})

Index Important Documents

Whenever you encounter documents important to the task, index them:

keep_flow(state="put", params={"uri": "https://docs.example.com/auth", "tags": {"topic": "auth", "project": "myapp"}})
keep_flow(state="put", params={"uri": "file:///path/to/design.pdf", "tags": {"kind": "reference", "topic": "architecture"}})

Ask: what is this? Why is it important? Tag appropriately.

NOTE: With the CLI you can index and watch full directory structures, including Git repositories. Caution: processing large directories will consume significant resources.

The ability to index, version, cross-reference and link external sources allows you to use memory for provenance, not just summary context.

Breakdowns as Learning

When the normal flow is interrupted — an assumption has been revealed. First: complete the immediate conversation. Then record:

keep_flow(state="put", params={"content": "Assumed user wanted full rewrite. Actually: minimal patch.", "tags": {"kind": "breakdown"}})

Breakdowns are how agents learn.

Tracking Commitments

Use speech-act tags to make the commitment structure visible:

// Track promises
keep_flow(state="put", params={"content": "I'll fix the auth bug", "tags": {"act": "commitment", "status": "open", "project": "myapp"}})

// Track requests
keep_flow(state="put", params={"content": "Please review the PR", "tags": {"act": "request", "status": "open"}})

// Query open work
keep_flow(state="list", params={"tags": {"act": "commitment", "status": "open"}})

// Close the loop
keep_flow(state="tag", params={"id": "ID", "tags": {"status": "fulfilled"}})

You should actively manage the list of open commitments. Fulfilled? Tag them.

See [TAGGING.md](use keep_help with topic="tagging") for the full speech-act framework.

Data Model

An item has:

  • A unique identifier (see below)
  • Timestamps (_created, _updated)
  • A summary of the content
  • Tags ({key: value, ...})
  • Version history (previous versions archived automatically)

The full original document is not stored. Summaries are contextual — tags shape how new items are understood. See [KEEP-PUT.md](use keep_help with topic="keep-put").

Item IDs

IDs are strings. The format tells you what kind of item it is:

Format Meaning Versioning Example
%hexhash Content-addressed — derived from content hash Usually single version %a1b2c3d4e5f6
.prefix/name System doc — bundled with keep Managed by keep .library/mn61, .tag/act, .conversations
https://... Web URL — ingested document Accumulates versions https://docs.example.com/auth
file:///... Local file — ingested document Accumulates versions file:///path/to/design.pdf
custom-name Named by user or agent Accumulates versions auth-decisions, meeting-notes
now Working context — current intentions Accumulates versions now

Content-addressed IDs (%hex): When you put content without specifying an id, keep hashes the content and uses %hash as the ID. These are stable — the same content always produces the same ID. They don't typically accumulate versions because re-putting the same content is a no-op.

now: By convention (it's just an item with ID now): use to track current working context and intentions. The get_now() API and keep now CLI are convenience shortcuts for get("now"). Each put to now creates a new version, building a trace of how intentions evolved.

Version selectors: Append @V{N} to read a specific version: now@V{1} (previous), now@V{2} (two back), now@V{-1} (oldest). Parts use @P{N}: doc@P{1} (first structural part).

System Documents

Bundled system docs provide patterns and conventions, accessible via get:

ID What it provides
.domains Domain-specific organization patterns
.conversations Conversation framework (action, possibility, clarification)
.tag/act Speech-act categories
.tag/status Lifecycle states
.tag/project Project tag conventions
.tag/topic Topic tag conventions

See Also

  • [FLOW-ACTIONS.md](use keep_help with topic="flow-actions") — Action reference
  • [KEEP-FLOW.md](use keep_help with topic="keep-flow") — Running and steering flows
  • [REFERENCE.md](use keep_help with topic="reference") — CLI quick reference
  • [TAGGING.md](use keep_help with topic="tagging") — Tags, speech acts, project/topic