Python API Reference

pip install keep-skill

pip install keep-skill[langchain]

from keep import Keeper

kp = Keeper()  # Uses ~/.keep/ by default

# Index documents
kp.put(uri="file:///path/to/doc.md", tags={"project": "myapp"})
kp.put(uri="https://example.com/page", tags={"topic": "reference"})
kp.put("Important insight about auth patterns")

# Search
results = kp.find("authentication", limit=5)
for r in results:
    print(f"[{r.score:.2f}] {r.id}: {r.summary}")

# Retrieve
item = kp.get("file:///path/to/doc.md")
print(item.summary)
print(item.tags)

from keep import Keeper, Item
from keep.document_store import VersionInfo, PartInfo  # for version/part history
from keep.types import ItemContext, PromptInfo, PromptResult

# Default store (~/.keep/)
kp = Keeper()

# Custom store location
kp = Keeper(store_path="/path/to/store")

from pathlib import Path
from keep.config import load_config
from keep.remote import RemoteKeeper

config = load_config(Path.home() / ".keep")
remote = RemoteKeeper(
    "https://api.keepnotes.ai",
    api_key="kn_...",
    config=config,
    project="my-project",
)

item = remote.put("Important hosted note", tags={"project": "my-project"})
hits = remote.find("hosted note", limit=5)
info = remote.server_info()

# Index from URI (file:// or https://)
kp.put(uri=uri, tags={}, summary=None) → Item

# Index inline content
kp.put(content, tags={}, summary=None) → Item

# Full signature:
# kp.put(content=None, *, uri=None, id=None, summary=None,
#        tags=None, created_at=None, force=False) → Item

# Notes:
# - Exactly one of content or uri must be provided
# - If summary provided, skips auto-summarization
# - Inline content used verbatim if short (≤max_summary_length)
# - User tags (domain, topic, etc.) provide context for summarization
# - id: override auto-generated ID (for managed imports)
# - created_at: ISO timestamp override (for historical imports)
# - force: re-process even if content unchanged

# Semantic search (default)
kp.find("auth", limit=10) → list[Item]

# With tag pre-filtering
kp.find("auth", tags={"user": "alice"}, limit=10) → list[Item]

# Scoped to specific IDs (glob pattern)
kp.find("auth", scope="file:///path/to/notes/*") → list[Item]

# Deep search — follow edges to discover related items
kp.find("auth", deep=True) → list[Item]

# Find similar to an existing note
kp.find(similar_to="note-id", limit=10) → list[Item]

# Time filtering
kp.find("auth", since="P7D")             # Last 7 days
kp.find("auth", since="P7D", until="P1D")  # Between 7 and 1 days ago
kp.find("auth", since="2026-01-15")      # Since date

# Full signature:
# kp.find(query=None, *, tags=None, similar_to=None, limit=10,
#         since=None, until=None, include_self=False,
#         include_hidden=False, deep=False, scope=None) → list[Item]

# Unified listing with composable filters (all optional, AND'd together)
kp.list_items(limit=10) → list[Item]
kp.list_items(tags={"project": "myapp"}, since="P7D")
kp.list_items(tag_keys=["act"], since="P3D")      # Key-only: any value
kp.list_items(prefix=".tag/act")                   # ID prefix
kp.list_items(order_by="accessed", limit=20)       # Sort by access time

# Get by ID
kp.get(id) → Item | None

# Check existence
kp.exists(id) → bool

# Update tags only (no re-processing)
kp.tag(id, tags={}) → Item | None

# Delete tag by setting empty value
kp.tag("doc:1", {"obsolete": ""})  # Removes 'obsolete' tag

# Remove tag keys entirely
kp.tag("doc:1", remove=["obsolete"])

# Remove specific values from a multi-value tag
kp.tag("doc:1", remove_values={"topic": "old-topic"})

# Edit tags on a part (parts are otherwise immutable)
kp.tag_part("doc:1", 1, tags={"topic": "oauth2"}) → PartInfo | None
kp.tag_part("doc:1", 1, tags={"topic": ""})  # Remove tag

# List tag keys or values
kp.list_tags(key=None) → list[str]
kp.list_tags()          # All tag keys
kp.list_tags("project") # All values for 'project' key

# Get previous version
kp.get_version(id, offset=1) → Item | None
# selector: 0=current, 1=previous, 2=two versions ago, -1=oldest archived

# List all versions
kp.list_versions(id, limit=10) → list[VersionInfo]

# Get navigation metadata
kp.get_version_nav(id, current_version=None, limit=3) → dict
# Returns: {"prev": [VersionInfo, ...], "next": [VersionInfo, ...]}

# Get current intentions (auto-creates if missing)
kp.get_now() → Item

# Per-user scoped intentions
kp.get_now(scope="alice") → Item

# Set current intentions
kp.set_now(content, tags={}) → Item

# Per-user scoped update (auto-tags user=alice)
kp.set_now(content, scope="alice") → Item

# Analyze a document into structural parts
kp.analyze(id) → list[PartInfo]

# List parts of an analyzed document
kp.list_parts(id) → list[PartInfo]

# Get a specific part
kp.get_part(id, part_num) → Item | None

# Run a state-doc flow (same as keep_flow MCP tool)
result = kp.run_flow("query-resolve", params={"query": "auth"})
# result.status, result.data, result.bindings, result.cursor
# (run_flow_command is an alias from the protocol — same call)

# Render an agent prompt with context injection
result = kp.render_prompt("reflect", "auth flow")
# result.prompt, result.context, result.search_results, result.flow_bindings

# Render with scoped search
result = kp.render_prompt("query", "auth", scope="file:///notes/*")

# Render with token budget (truncates context to fit)
result = kp.render_prompt("reflect", "auth", token_budget=4000)

# Move versions from one note to another
kp.move("target-id", source_id="source-id") → Item

# Move with new tags
kp.move("target-id", source_id="source-id", tags={"project": "new"})

# Move only the current version (not full history)
kp.move("target-id", source_id="source-id", only_current=True)

# Get complete display context for a note (similar, meta, parts, versions)
kp.get_context(id) → ItemContext | None

# Customize what's included
kp.get_context(id,
    include_similar=True, similar_limit=5,
    include_meta=True, meta_limit=5,
    edges_limit=5,
    include_parts=True, parts_limit=10,
    include_versions=True, versions_limit=5,
)

# Probe server capabilities
remote.server_info() → dict[str, Any]
remote.capabilities() → dict[str, Any]
remote.supports_capability("export_changes") → bool

# Export current state or sync incrementally
remote.export_data(include_system=False) → dict
remote.export_bundle(id) → dict | None
remote.export_changes(cursor=None, limit=1000) → dict

# Delete item and its versions
kp.delete(id) → bool
kp.delete(id, delete_versions=False) → bool  # Keep version history

# Delete a specific version
kp.delete_version(id, offset=1) → bool  # offset: 1=previous, 2=two ago, etc.

# Revert to previous version (if history exists)
kp.revert(id) → Item | None

# Count notes in store
kp.count() → int

# Count archived versions in a local store
kp.count_versions() → int

# List backing collections in a local store
kp.list_collections() → list[str]

# List available prompt templates
kp.list_prompts() → list[PromptInfo]

# Export all data (for backup/migration)
data = kp.export_data(include_system=False) → dict

# Import data
kp.import_data(data, mode="merge") → dict  # mode: "merge" or "replace"

# Close resources (embedding providers, etc.)
kp.close()

import os
os.environ["KEEP_TAG_PROJECT"] = "myapp"
os.environ["KEEP_TAG_OWNER"] = "alice"

kp.put("note")  # Auto-tagged with project=myapp, owner=alice

[tags]
project = "my-project"
owner = "alice"
required = ["user"]                    # Enforce required tags on put()
namespace_keys = ["category", "user"]  # LangGraph namespace mapping

kp.list_items(tags={"_updated_date": "2026-01-30"})
kp.list_items(tags={"_source": "inline"})

item = kp.get("doc:1@V{1}")  # Get previous version
versions = kp.list_versions("doc:1")

from keep import Keeper

try:
    kp = Keeper()
    item = kp.get("nonexistent")
    if item is None:
        print("Item not found")
except Exception as e:
    print(f"Error: {e}")