Reflective Memory — Agent Reference Card

keep --json  (-j) <cmd>  # Output as JSON
keep --ids   (-I) <cmd>  # Output only versioned IDs (for piping)
keep --full  (-F) <cmd>  # Output full YAML frontmatter
keep -v <cmd>            # Enable debug logging to stderr

%a1b2c3d4         2026-01-14 URI detection should use proper scheme validation...
%e5f6a7b8         (0.89) 2026-01-14 OAuth2 token refresh pattern...
file:///path/doc  2026-01-15 Document about authentication patterns...

%a1b2c3d4@V{0}
file:///path/doc@V{0}

---
id: %a1b2c3d4
tags:
  project: "myapp"
  status: "reviewed"
similar:
  - %e5f6a7b8@V{0} (0.89) 2026-01-14 Related authentication...
meta/todo:
  - %c9d0e1f2 Update auth docs for new flow
score: 0.823
prev:
  - @V{1} 2026-01-14 Previous summary text...
---
Document summary here...

{"id": "...", "summary": "...", "tags": {...}, "score": 0.823}

keep --ids find "auth" | xargs keep get              # Get full details for all matches
keep --ids list -n 5 | xargs keep get                # Get details for recent items
keep --ids list --tag project=foo | xargs keep tag --tag status=done
keep --json --ids find "query"                       # JSON array: ["id@V{0}", ...]

# Version history composition
keep --ids now --history | xargs -I{} keep get "{}"  # Get all versions
diff <(keep get doc:1) <(keep get "doc:1@V{1}")      # Diff current vs previous

# Current intentions
keep now                              # Show current intentions
keep now "What's important now"       # Update intentions
keep prompt reflect                   # Structured reflection practice
keep prompt reflect "auth flow"       # Reflect with search context
keep prompt query "what do I know about auth?"  # Answer from memory context
keep prompt conversation              # Conversation analysis
keep move "name" -t project=foo       # Move matching versions from now
keep move "name" --only               # Move just the current version
keep move "name" --from "source" -t X # Reorganize between items
keep move "name" --only --analyze     # Move + decompose into parts

# Add or update
keep put "inline text" -t topic=auth  # Text mode
keep put file:///path/to/doc.pdf      # URI mode
keep put /path/to/folder/             # Directory mode
keep put "note" --suggest-tags        # Show tag suggestions
keep put doc.pdf --analyze            # Index + decompose into parts

# Retrieve
keep get ID                           # Current version
keep get ID -V 1                      # Previous version
keep get "ID@P{1}"                    # Part 1 (from analyze)
keep get ID --history                 # List all versions
keep get ID --parts                   # List structural parts

# Search
keep find "query"                     # Semantic search
keep find "query" --text              # Full-text search
keep find "query" --deep              # Follow tags/edges to discover related items
keep find "query" --since P7D         # Last 7 days

# List and filter
keep list                            # Recent items
keep list --tag project=myapp        # Filter by tag
keep list --tags=                    # List all tag keys

# Modify
keep tag ID --tag key=value   # Add/update tag
keep tag ID --remove key      # Remove tag
keep tag "ID@P{1}" -t topic=x # Edit tags on a part
keep del ID                          # Remove item or revert to previous version

# Analyze (skips if parts are already current)
keep analyze ID                      # Decompose into parts (background)
keep analyze ID -t topic -t type     # With guidance tags
keep analyze ID --fg                 # Wait for completion
keep analyze ID --force              # Re-analyze even if current

# Data management
keep data export backup.json         # Export store to JSON
keep data export - | gzip > bk.gz    # Export to stdout, compress
keep data import backup.json         # Import (merge, skip existing)
keep data import backup.json -m replace  # Import (replace all)

# Maintenance
keep pending                         # Process pending tasks, tail progress
keep pending --reindex               # Re-embed all items + process
keep pending --retry                 # Reset failed items back to pending
keep pending --stop                  # Stop background processor

from keep import Keeper
kp = Keeper()
kp.put("note", tags={"project": "myapp"})
results = kp.find("authentication", limit=5)

from keep.langchain import KeepStore, KeepNotesToolkit, KeepNotesRetriever