Keep API Schema Reference

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

Interface: MCP tools (prefixed keep_), CLI (keep <cmd>), or Python (Keeper).

Data Model

Item

Every piece of stored content is an item.

FieldTypeDescription
idstringUnique identifier (see ID Formats below)
summarystringGenerated or user-provided summary of the content
tags{key: value}Key-value metadata. Values are strings or lists of strings
scorefloat or nullSimilarity score (0-1), present only in search results

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 (keep_tag) and unchanged writes update in place.

SelectorMeaning
@V{0}Current version (default)
@V{1}Previous version
@V{N}N versions back
@V{-1}Oldest archived version

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.

SelectorMeaning
@P{1}First part (1-indexed)
@P{N}Nth part

Parts appear independently in search results. Retrieve with: keep_get(id="DOC_ID@P{1}")

ID Formats

FormatExampleCreated by
%hexhash%a1b2c3d4e5f6Inline text when id is omitted (CLI, MCP, Python API)
URLhttps://example.com/docURI put
file:// URIfile:///path/to/doc.pdfLocal file put
Custom stringmy-notesUser-specified id parameter
nownowWorking context (singleton)
.tag/KEY.tag/actTag description (system doc)
.tag/KEY/VALUE.tag/act/commitmentTag value description (system doc)

Tags

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

Setting and removing

keep_tag(id="ID", tags={"topic": "auth"})           # set
keep_tag(id="ID", tags={"old-tag": ""})              # remove (empty string)
keep_put(content="text", tags={"project": "myapp"})  # set on create

Filtering

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

keep_find(query="auth", tags={"project": "myapp"})
keep_list(tags={"status": "open"})

Multiple tags use AND logic: all must match.

Built-in tags

KeyConstrainedSingularValues
actyesyescommitment, request, offer, assertion, assessment, declaration
statusyesyesopen, blocked, fulfilled, declined, withdrawn, renegotiated
typenonolearning, breakdown, gotcha, reference, teaching, meeting, pattern, possibility, decision
projectnonouser-defined
topicnonouser-defined

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.

Time Filters

Both since and until accept two formats:

FormatExampleMeaning
ISO 8601 durationP3D3 days ago
P1W1 week ago
P1M~30 days ago
PT1H1 hour ago
P1Y~365 days ago
Date2026-01-15Specific date

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

Tools

keep_put

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

ParameterTypeRequiredDefaultDescription
contentstringyes—Text to store, or URI (http://, https://, file://) to fetch and index
idstringnoautoCustom ID. If omitted: URI inputs use the URI as ID; inline text uses a content hash
summarystringnoautoUser-provided summary (skips auto-summarization)
tags{str: str}nononeTags to set. Example: {"topic": "auth"}
analyzeboolnofalseDecompose into searchable parts after storing

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

Examples: 

keep_put(content="OAuth2 uses PKCE for public clients", tags={"topic": "auth"})
keep_put(content="https://docs.example.com/api", tags={"type": "reference"})
keep_put(content="Long document...", analyze=true)
keep_put(content="My design notes", id="design-notes", summary="Architecture decisions")

keep_find

Search memory by meaning. Returns items ranked by semantic similarity with recency weighting.

ParameterTypeRequiredDefaultDescription
querystringyes—Natural language search query
tags{str: str}nononePre-filter: only search items matching all tags
sincestringnononeTime filter (see Time Filters)
untilstringnononeTime filter (see Time Filters)
deepboolnofalseFollow tags and edges to discover related items beyond direct matches
show_tagsboolnofalseInclude non-system tags in each result
token_budgetintno4000Approximate token budget for the response

Returns: Formatted list of results, one per line: 

- ID  (score) date  summary text...

Examples: 

keep_find(query="authentication patterns")
keep_find(query="open tasks", tags={"project": "myapp"}, since="P7D")
keep_find(query="architecture decisions", deep=true, token_budget=8000)

keep_get

Retrieve one item with full context: similar items, meta sections, structural parts, and version history.

ParameterTypeRequiredDefaultDescription
idstringyes—Item ID. Use "now" for current working context

Returns: YAML frontmatter with 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...
prev:
  - @V{1} 2026-01-13 Previous version summary...
---
Item summary or content here

Examples: 

keep_get(id="now")              # current working context
keep_get(id="%a1b2c3")          # specific item
keep_get(id="%a1b2c3@V{1}")    # previous version
keep_get(id="%a1b2c3@P{1}")    # first structural part
keep_get(id=".tag/act")         # tag description doc

keep_now

Update the current working context. Persists across sessions. Implemented via put(id="now", ...), so it creates a version when content changes.

ParameterTypeRequiredDefaultDescription
contentstringyes—Current state, active goals, recent decisions
tags{str: str}nononeTags for this context update

Returns: "Context updated: now"

To read current context, use keep_get(id="now").

Examples: 

keep_now(content="Investigating flaky auth test. Suspect timing issue.")
keep_now(content="Fixed the bug. Next: add regression test.", tags={"project": "myapp"})

keep_tag

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

ParameterTypeRequiredDefaultDescription
idstringyes—Item ID
tags{str: str}yes—Tags to set. Empty string "" deletes the tag

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

Examples: 

keep_tag(id="%a1b2c3", tags={"status": "fulfilled"})
keep_tag(id="%a1b2c3", tags={"topic": "auth", "obsolete": ""})

keep_delete

Permanently delete an item and all its versions.

ParameterTypeRequiredDefaultDescription
idstringyes—Item ID to delete

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

keep_list

List recent items. Supports filtering by ID prefix, tags, and time range.

ParameterTypeRequiredDefaultDescription
prefixstringnononeID prefix or glob pattern (e.g. ".tag/*")
tags{str: str}nononeFilter by tag key=value pairs
sincestringnononeTime filter
untilstringnononeTime filter
limitintno10Maximum results

Returns: List of items, one per line: 

- ID  date  summary text...

Examples: 

keep_list()                                              # recent items
keep_list(tags={"act": "commitment", "status": "open"})  # open commitments
keep_list(prefix=".tag/*")                               # all tag docs
keep_list(since="P7D", limit=20)                         # last week, up to 20

keep_move

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

ParameterTypeRequiredDefaultDescription
namestringyes—Target item ID (created if new, appended if exists)
source_idstringno"now"Source item to extract from
tags{str: str}nononeOnly move versions whose tags match (all must match)
only_currentboolnofalseMove only the tip version, not full history

Returns: "Moved to: my-notes"

Examples: 

keep_move(name="auth-work", tags={"project": "myapp"})     # archive matching versions from now
keep_move(name="design-log", only_current=true)             # snapshot current context
keep_move(name="topic-notes", source_id="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.

ParameterTypeRequiredDefaultDescription
namestringnononePrompt name. Omit to list available prompts
textstringnononeSearch query for {find} placeholder
idstringno"now"Item ID for {get} placeholder
tags{str: str}nononeFilter search context by tags
sincestringnononeTime filter for search context
untilstringnononeTime filter for search context
deepboolnofalseFollow tags to discover related items
token_budgetintnotemplate defaultToken budget for search results

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

Available prompts:

NamePurpose
reflectStructured reflection on actions and outcomes
session-startContext and open commitments at session start
queryAnswer a question using memory context
conversationConversation analysis
subagent-startSubagent initialization context

Examples: 

keep_prompt()                                          # list available prompts
keep_prompt(name="reflect")                            # reflect on current context
keep_prompt(name="session-start")                      # start-of-session context
keep_prompt(name="query", text="what do I know about auth?")
keep_prompt(name="reflect", text="deployment", since="P3D")

Common Patterns

Session lifecycle

keep_prompt(name="session-start")                      # 1. orient
keep_get(id="now")                                     # 2. check intentions
# ... do work ...
keep_now(content="Completed X. Next: Y.")              # 3. update context
keep_prompt(name="reflect")                            # 4. reflect

Store and retrieve

keep_put(content="insight text", tags={"type": "learning", "topic": "auth"})
keep_find(query="authentication insights")
keep_get(id="%returned_id")

Track commitments

keep_put(content="Will fix bug by Friday", tags={"act": "commitment", "status": "open"})
keep_list(tags={"act": "commitment", "status": "open"})   # check open work
keep_tag(id="ID", tags={"status": "fulfilled"})            # close the loop

Index a document

keep_put(content="https://docs.example.com/api", tags={"type": "reference", "topic": "api"})
keep_find(query="API documentation")

Archive and pivot

keep_move(name="auth-work", tags={"project": "myapp"})     # archive
keep_now(content="Starting on database migration")          # fresh context

See Also