Snipara
LoginStart

Python SDK

Unified Python SDK for Snipara. One config file, one CLI, one API. Context optimization, agent memory, file sync, and code execution — all from a single snipara package.

New in v0.1.0

The snipara package consolidates 5 separate configuration systems into a single .snipara.toml file, provides a unified async/sync Python API wrapping the Snipara MCP server, event-driven file synchronization, and an auto-feedback loop (query → execute → remember).

Installation

Core (context queries, memory, config)

pip install snipara

With file watcher

pip install snipara[watch]

With RLM code execution

pip install snipara[runtime]

Everything

pip install snipara[all]

Requirements

  • Python 3.10+ (3.11+ recommended for native TOML support)
  • snipara-mcp >= 2.3.0 (installed automatically)
  • watchfiles >= 0.21.0 (optional, for snipara watch)
  • rlm-runtime >= 0.1.0 (optional, for snipara execute)

Quick Start

1. Initialize Configuration

snipara init

This creates .snipara.toml in your project root interactively. You'll be prompted for your project slug, API key, default token budget, search mode, and optional runtime settings.

2. Query Context (Async)

from snipara import Snipara
async with Snipara() as s:
    result = await s.query("how does authentication work?")
    for section in result.get("sections", []):
        print(f"[{section['relevance']:.0%}] {section['title']}")
        print(section["content"][:200])

3. Query Context (Sync)

from snipara import SniparaSync
with SniparaSync() as s:
    result = s.query("how does authentication work?")
    print(result)

Sync client works in Jupyter

SniparaSync handles nested event loops automatically, so it works in Jupyter notebooks without any special setup.

4. Full Feedback Loop

from snipara import Snipara
async with Snipara() as s:
    # query -> execute -> remember (all in one call)
    result = await s.run(
        "fix the rate limiting bug in the API",
        remember_learnings=True,
    )
    print(f"Context tokens: {result.context.total_tokens}")
    print(f"Execution: {result.execution.summary}")
    print(f"Memories stored: {len(result.memories_stored)}")

Configuration

The .snipara.toml file is the single source of truth for all Snipara settings. Place it in your project root (alongside .git/).

PROJECT - Authentication and API connection
[project]
slug = "my-project"
api_key = "rlm_abc123def456..."
api_url = "https://api.snipara.com"
CONTEXT - Query defaults
[context]
max_tokens = 4000
search_mode = "hybrid"
include_summaries = true
shared_context = true
RUNTIME - rlm-runtime code execution
[runtime]
backend = "anthropic"
model = "claude-sonnet-4-20250514"
environment = "local"
max_depth = 4
SYNC - File watcher patterns
[sync]
include = ["docs/**/*.md", "*.md"]
exclude = ["node_modules/**", ".git/**"]
debounce_ms = 500

Resolution Order

Configuration is resolved with layered priority (highest wins):

1 (highest)Environment variables

SNIPARA_API_KEY, SNIPARA_PROJECT_ID, etc.

2.snipara.toml (project)

Walk up from CWD to git root

3~/.config/snipara/config.toml

Global user defaults

4rlm.toml (legacy)

Deprecated - emits warning

5 (lowest)Built-in defaults

Hardcoded in Pydantic models

SDK API Reference

The SDK provides both async (Snipara) and sync (SniparaSync) clients with the same API surface. All methods below are shown in async form.

Context Optimization

query(query)

Query for optimized, ranked context sections

Params: max_tokens, search_mode

search(pattern)

Search documentation with regex patterns

Params: max_results

plan(query)

Generate execution plan for complex queries

Params: strategy, max_tokens

multi_query(queries)

Execute multiple queries with shared budget

Params: max_tokens

shared_context()

Get merged team shared context

Params: categories, max_tokens

Document Management

upload(path, content)

Upload or update a single document

Params: path, content

sync_documents(documents)

Bulk sync multiple documents

Params: delete_missing

Agent Memory

remember(content)

Store a memory for later semantic recall

Params: type, scope, category, ttl_days

recall(query)

Semantically recall relevant memories

Params: limit, min_relevance, type

Code Execution & Feedback Loop

execute(task)

Execute a task via rlm-runtime (requires [runtime])

Params: context, environment, max_depth

run(task)

Complete feedback loop: query > execute > remember

Params: context_query, remember_learnings, memory_types

Result Types

QueryResult

Context query result

Fields: sections, total_tokens, suggestions

SearchResult

Regex search result

Fields: matches, total_matches

PlanResult

Execution plan

Fields: steps, total_tokens

ExecuteResult

Code execution result

Fields: response, trajectory, total_cost

RunResult

Full feedback loop result

Fields: context, execution, memories_stored

MemoryResult

Remember/recall result

Fields: memory_id, memories

SyncResult

Bulk sync result

Fields: created, updated, deleted

CLI Reference

The snipara CLI is installed automatically with the SDK. All commands work from any directory within a project that has a .snipara.toml.

snipara init

Create or migrate .snipara.toml

Example: snipara init --migrate

snipara config

View resolved config or file path

Example: snipara config show

snipara status

Show auth, config, and runtime status

Example: snipara status

snipara login

Authenticate via browser (device flow)

Example: snipara login

snipara logout

Clear stored tokens

Example: snipara logout

snipara query

Query documentation from the CLI

Example: snipara query "auth" --max-tokens 8000

snipara sync

One-shot sync of local files

Example: snipara sync --dry-run

snipara watch

Watch and sync changes in real-time

Example: snipara watch

File Watcher

The snipara watch command uses watchfiles (Rust-based, cross-platform, async) to monitor your project for file changes and automatically sync them to Snipara.

snipara watch
Watching /project (2 include, 4 exclude patterns)
Synced: docs/api.md
Synced: docs/auth.md

Configure patterns in the [sync] section of .snipara.toml:

[sync]
include = ["docs/**/*.md", "*.md", "src/**/*.py"]
exclude = ["node_modules/**", ".git/**", "dist/**"]
debounce_ms = 500

Dry run

Lists files, no uploads

snipara sync --dry-run

One-shot

Syncs all files once, then exits

snipara sync

Watch

Continuous sync on file changes

snipara watch

Key behaviors

  • Debounce: Configurable via sync.debounce_ms (default 500ms)
  • Binary files: Automatically skipped with a warning
  • Upload errors: Logged but don't stop the watcher
  • Exclude patterns checked first, then include patterns

Relationship to snipara-mcp

The snipara SDK wraps the snipara-mcp HTTP client internally. All API calls go through snipara_mcp.rlm_tools.SniparaClient — there is no HTTP duplication.

The SDK adds on top of snipara-mcp: unified .snipara.toml configuration, the snipara CLI, file watcher/sync, rlm-runtime integration, and the auto-feedback loop. It is not a replacement but a higher-level abstraction. You can still use snipara-mcp directly for MCP server connections (Claude Code, VS Code, Cursor, etc.).

Next Steps

MCP Tools Reference

Full documentation for all 43 Snipara MCP tools.

RLM Runtime

Safe code execution with Docker isolation and trajectory logging.

Agent Memory

Remember decisions and context across sessions.

Other Integrations

Claude Code, VS Code, Cursor, Windsurf, and more.