Guides

keep is a reflective memory system for AI agents.

Getting Started

The REST API Quick Start walks through storing notes, semantic search, file uploads (PDF, markdown), document analysis, and cross-source retrieval using curl — all in about five minutes. The CLI Quick Start covers installing via uv tool install keep-skill, configuring embedding providers (Voyage AI, OpenAI, Gemini, Mistral, Ollama, or local MLX models on Apple Silicon), and your first keep put / keep find cycle.

CLI Commands

Concepts

Reference

All Guides

Complete listing of every guide with summary:

REST API Quick Start

Store notes, search by meaning, upload files, analyze documents, and retrieve cross-source results — all via HTTP. Bearer-token auth, JSON responses, five-minute walkthrough.

CLI Quick Start

Install keep with uv tool install keep-skill, configure an embedding provider (Voyage AI, OpenAI, Gemini, Mistral, Ollama, or local MLX), store your first note, and run a semantic search.

keep put

Store content from inline text, stdin, file paths, directories (recursive), or HTTP/HTTPS URLs. Supports custom IDs, tags, and automatic embedding on store. Handles PDF, markdown, and plain text.

keep get

Retrieve a note by exact ID or prefix match. Returns content, all tags, version count, and meta-tag relationships (similar notes, learnings, previous versions).

keep find

Semantic similarity search across all stored notes. Specify a query string; returns ranked results with similarity scores. Filter by tag key-value pairs, set minimum similarity threshold, limit result count.

keep list

List notes with filters: by tag, date range, source type, ID pattern. Sort by creation date, update date, or access time. Output as YAML, JSON, or compact single-line format.

keep now

The now note is a single mutable record representing your agent's current state, goals, and working context. Read it to recall active intentions; write it to update direction. Related notes and learnings surface automatically as meta-tag fields.

keep move

Rename notes (change ID), update tags in bulk, reorganize between locations. Preserves version history through moves.

keep analyze

Break long documents into individually searchable structural parts. Each part gets its own embedding. Analyze finds themes, sections, key arguments, and cross-references — making large documents discoverable at the paragraph level.

keep prompt

Render agent prompts with context injected from reflective memory. Built-in prompts for reflection, session starts, and conversation analysis — or create custom prompts.

keep data

Export and import keep stores for backup and migration. Move data between local SQLite and cloud PostgreSQL backends.

keep config

Configure storage backend (SQLite local, PostgreSQL cloud), embedding provider and model, similarity thresholds, and other settings via environment variables or ~/.keep/config.toml.

Tagging

Structured key-value tags: domain: healthcare, thread: margaret, facet: metabolic. Tags enable precise filtering alongside semantic search. Thread-level tags provide hard links that similarity alone can't maintain.

System Tags

Automatic tags managed by keep: _created (ISO timestamp), _updated (last modification), _accessed (last read), _source (inline, file, url, stdin). Cannot be manually set.

Meta-Tags

Metaschema rules define how notes relate. similar surfaces semantically close notes. meta/learnings extracts insights tagged as learnings. prev shows version history. Meta-tags give agents longitudinal awareness — context compounds over time.

Edge Tags

Turn tags into navigable relationship edges. When a tagdoc declares _inverse, tagged documents become links — and targets get automatic inverse listings. Tag a conversation with speaker: Deborah and get Deborah shows everything she said. Targets auto-vivify on first reference.

Versioning

Every keep put to an existing ID creates a new version. List versions, retrieve any version by number, compare across versions. Content-hash deduplication skips unchanged updates.

Analysis

How document analysis decomposes long content into individually searchable structural parts. Each part gets its own embedding and tags, improving retrieval for large documents.

Output Format

Keep outputs YAML frontmatter (tags, metadata, meta-tags) followed by content body. Supports --format json for machine parsing, --compact for single-line summaries, and full (default) for human reading.

CLI Reference

Complete command reference: put, get, find, list, now, move, analyze, config, save, remember. Every flag, option, and environment variable documented with examples.

Python API

The Keeper class provides programmatic access: put(), get(), find(), list(), now(), analyze(). Sync API (no async needed). Install with pip install keep-skill.

Architecture

Technical internals: SQLite + FTS5 for local storage, PostgreSQL + pgvector for cloud. Embedding pipeline (Voyage, OpenAI, Gemini, Mistral, Ollama, MLX). Background worker for async tasks. Content-hash deduplication. Meta-tag resolution engine.

Agent Guide

Patterns for AI agents using keep effectively: store decisions and learnings (not raw logs), use now for session continuity, let meta-tags surface context automatically, reflect before and after significant actions (MN61 mirror teaching).

MCP (keep CLI)

Local MCP stdio server for AI agent integration. Connect Claude Code, Cursor, and other MCP-compatible clients directly to your local keep store.

MCP (keepnotes.ai)

Model Context Protocol server at /mcp. Auto-generated from OpenAPI spec — MCP-compatible AI assistants discover and use keep commands as native tools with zero configuration.

OpenClaw Integration

Three-layer integration pattern: (1) Skill prompt injects keep now context every agent turn, (2) after_compaction hook auto-indexes memory files, (3) Daily cron runs keep put memory/ --analyze for deep reflection. Turns keep from a tool into a continuous practice.