Keep API Schema Reference

Concise reference for the keep memory API. Covers the data model, tools, parameter types, and return formats.

Interface: MCP (keep_flow, keep_prompt, keep_help), CLI (keep <cmd>), or Python (Keeper).

The MCP boundary is keep_flow(state, params) — every operation is a state-doc invocation. Examples below show the JSON payload that goes into the params field.

Data Model

Item

Every piece of stored content is an item.

Items also carry system-managed timestamps in tags: _created, _updated, _accessed.

Versions

New archived versions are created when put updates an existing item's content. Tag-only updates (tag) and unchanged writes update in place.

Append the selector to any ID: %a1b2c3@V{1}

Parts

analyze decomposes a document into structural parts — sections with their own summaries, tags, and embeddings.

Parts appear independently in search results. Retrieve with:

keep_flow(state="get", params={"item_id": "DOC_ID@P{1}"})

ID Formats

Tags

Key-value pairs on every item. Keys are alphanumeric (plus _, -). Values are strings or lists of strings.

Setting and removing

keep_flow(state="tag", params={"id": "ID", "tags": {"topic": "auth"}})
keep_flow(state="tag", params={"id": "ID", "tags": {"old-tag": ""}})
keep_flow(state="put", params={"content": "text", "tags": {"project": "myapp"}})

Empty string value removes the tag.

Filtering

Tags on find and list are pre-filters — the search only considers matching items.

keep_flow(state="query-resolve", params={"query": "auth", "tags": {"project": "myapp"}})
keep_flow(state="list", params={"tags": {"status": "open"}})

Multiple tags use AND logic: all must match.

Built-in tags

Constrained: only listed values accepted. Singular: new values replace old (not accumulate).

System tags (auto-managed, read-only)

_created, _updated, _updated_date, _accessed, _accessed_date, _source, _content_type

These are hidden from default display but accessible via --json or Python API. See SYSTEM-TAGS.md for the full list.

Time Filters

Both since and until accept two formats:

since = items updated on or after. until = items updated before.

Tools

put (state doc)

Store text, a URL, or a document. For inline text without an explicit id, keep uses a content-addressed ID.

Exactly one of content or uri is required. After storing, the after-write flow runs in the background to summarize, tag, analyze, and link the item — this is governed by .state/after-write and is not a parameter on put.

Returns: "Stored: %a1b2c3" or "Unchanged: %a1b2c3" (idempotent on same content)

Examples:

keep_flow(state="put", params={"content": "OAuth2 uses PKCE for public clients", "tags": {"topic": "auth"}})
keep_flow(state="put", params={"uri": "https://docs.example.com/api", "tags": {"kind": "reference"}})
keep_flow(state="put", params={"content": "My design notes", "id": "design-notes", "summary": "Architecture decisions"})

query-resolve (state doc)

Search memory by meaning. Returns items ranked by semantic similarity with recency weighting. This is the iterative entry point — it routes between query-branch and query-explore when results are ambiguous. See FLOWS.md for the state machine.

Returns: Formatted list of results, one per line:

- ID  (score) date  summary text...

Examples:

keep_flow(state="query-resolve", params={"query": "authentication patterns"})
keep_flow(state="query-resolve", params={"query": "open tasks", "tags": {"project": "myapp"}, "since": "P7D"})
keep_flow(state="query-resolve", params={"query": "architecture decisions", "deep": true})

get (state doc)

Retrieve one note in note-first form, with attached context. The result starts with the requested note's tags and body, then may include contextual sections such as similar notes, meta sections, structural parts, linked items, and version navigation.

Returns: YAML frontmatter for the requested note plus any available context sections:

---
id: %a1b2c3
tags:
  project: "myapp"
  topic: "auth"
similar:
  - %e5f6a7 (0.89) 2026-01-14 Related item summary...
meta/todo:
  - %d3e4f5 Open task related to this item...
parts:
  - @P{1} Section one summary...
edges/informs:
  - other-note  Related note surfaced via edge tags...
prev:
  - @V{1} 2026-01-13 Previous version summary...
---
Item summary or content here

The exact attached sections depend on what exists for the requested note. Tags are always part of the returned note shape; similar, meta/*, parts, edges/*, prev, and next appear when relevant.

Examples:

keep_flow(state="get", params={"item_id": "now"})
keep_flow(state="get", params={"item_id": "%a1b2c3"})
keep_flow(state="get", params={"item_id": "%a1b2c3@V{1}"})
keep_flow(state="get", params={"item_id": "%a1b2c3@P{1}"})
keep_flow(state="get", params={"item_id": ".tag/act"})

Updating now

The current working context is just an item with id="now". To update it, use put:

keep_flow(state="put", params={"id": "now", "content": "Investigating flaky auth test. Suspect timing issue."})
keep_flow(state="put", params={"id": "now", "content": "Fixed the bug. Next: add regression test.", "tags": {"project": "myapp"}})

Each call creates a new version of the now item. To read current context, use keep_flow(state="get", params={"item_id": "now"}).

tag (state doc)

Add, update, or remove tags on an existing item. Does not re-process content.

Returns: "Tagged %abc: set topic=auth; removed old-tag"

Examples:

keep_flow(state="tag", params={"id": "%a1b2c3", "tags": {"status": "fulfilled"}})
keep_flow(state="tag", params={"id": "%a1b2c3", "tags": {"topic": "auth", "obsolete": ""}})

delete (state doc)

Permanently delete an item and all its versions.

Returns: "Deleted: %a1b2c3" or "Not found: %a1b2c3"

keep_flow(state="delete", params={"id": "%a1b2c3"})

list (state doc)

List recent items. Supports filtering by ID prefix, tags, and time range. This is plain enumeration, distinct from query-resolve which does semantic search.

Returns: List of items, one per line:

- ID  date  summary text...

Examples:

keep_flow(state="list", params={})
keep_flow(state="list", params={"tags": {"act": "commitment", "status": "open"}})
keep_flow(state="list", params={"prefix": ".tag/", "include_hidden": true})
keep_flow(state="list", params={"since": "P7D", "limit": 20})

move (state doc)

Move versions from a source item into a named target. Used to archive working context or reorganize notes.

Note: The MCP/flow parameter is source (matching the wrapper at .state/move). The Python API method kp.move() uses source_id= for the same field — historical name, same meaning.

Returns: "Moved to: my-notes"

Examples:

keep_flow(state="move", params={"name": "auth-work", "tags": {"project": "myapp"}})
keep_flow(state="move", params={"name": "design-log", "only_current": true})
keep_flow(state="move", params={"name": "topic-notes", "source": "old-doc", "tags": {"topic": "auth"}})

keep_prompt

Render an agent prompt template with live context injected from memory. Templates use {get} and {find} placeholders that expand to current item context and search results, plus any bindings from a state-doc-backed prompt's flow.

Signature comes from Keeper.render_prompt() in keep/_context_resolution.py.

Returns: Rendered prompt text with placeholders expanded, or list of available prompts.

Bundled prompts (see keep list .prompt/agent --all):

The system* and *-assemble prompts are intended for host integrations (Hermes, OpenClaw) rather than direct agent invocation, but they're discoverable here for completeness. Custom prompts can be added under .prompt/agent/.

Examples:

keep_prompt()
keep_prompt(name="reflect")
keep_prompt(name="session-start")
keep_prompt(name="query", text="what do I know about auth?")
keep_prompt(name="reflect", text="deployment", since="P3D")
keep_prompt(name="query", text="auth", tags={"project": "myapp"}, deep=true)
keep_prompt(name="query", text="api docs", scope="https://docs.example.com/*")

Common Patterns

Session lifecycle

keep_prompt(name="session-start")
keep_flow(state="get", params={"item_id": "now"})
keep_flow(state="put", params={"id": "now", "content": "Completed X. Next: Y."})
keep_prompt(name="reflect")

Store and retrieve

keep_flow(state="put", params={"content": "insight text", "tags": {"kind": "learning", "topic": "auth"}})
keep_flow(state="query-resolve", params={"query": "authentication insights"})
keep_flow(state="get", params={"item_id": "%returned_id"})

Track commitments

keep_flow(state="put", params={"content": "Will fix bug by Friday", "tags": {"act": "commitment", "status": "open"}})
keep_flow(state="list", params={"tags": {"act": "commitment", "status": "open"}})
keep_flow(state="tag", params={"id": "ID", "tags": {"status": "fulfilled"}})

Index a document

keep_flow(state="put", params={"uri": "https://docs.example.com/api", "tags": {"kind": "reference", "topic": "api"}})
keep_flow(state="query-resolve", params={"query": "API documentation"})

Archive and pivot

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

See Also

• AGENT-GUIDE.md — Working session patterns and reflective practice
• TAGGING.md — Full tag system reference (speech acts, constraints, edge tags)
• OUTPUT.md — How to read the YAML frontmatter output format
• KEEP-MCP.md — MCP server setup and integration
• REFERENCE.md — CLI command reference