capsule-ai

Thin Python client for Kapsule, atomic file-first memory for AI agents.

This package only talks to the Capsule HTTP API. The engine, CLI, and framework adapters stay in the kapsule package on PyPI.

Install

pip install capsule-ai

Use

The API listens on http://127.0.0.1:9100 by default. Pass api_token when the server has CAPSULE_API_TOKEN.

import os
from capsule_ai import KapsuleClient

with KapsuleClient(
    base_url="http://127.0.0.1:9100",
    api_token=os.environ.get("CAPSULE_API_TOKEN"),
) as kapsule:
    created = kapsule.create_capsule(
        topic="Auth middleware bypass in staging",
        content="Staging skips the JWT check on /internal/health.",
        tags=["auth", "bug"],
        confidence="high",
    )
    matches = kapsule.search("JWT authentication", mode="fts")
    context = kapsule.compose(query="database concurrency and auth", max_tokens=400)
    print(created["id"], len(matches), context["context"])

Methods

Method	API
`health`	`GET /health`
`status`	`GET /api/v1/status`
`create_capsule`	`POST /api/v1/capsules`
`list_capsules`	`GET /api/v1/capsules`
`get_capsule`	`GET /api/v1/capsules/{id}`
`update_capsule`	`PATCH /api/v1/capsules/{id}`
`delete_capsule`	`DELETE /api/v1/capsules/{id}`
`archive_capsule`	`POST /api/v1/capsules/{id}/archive`
`search`	`POST /api/v1/search`
`compose`	`POST /api/v1/compose`
`list_relationships` / `create_relationship`	`/api/v1/relationships`
`capsule_relationships`	`GET /api/v1/capsules/{id}/relationships`
`list_tags`	`GET /api/v1/tags`
`stale`	`GET /api/v1/stale`
`sync`	`POST /api/v1/sync`

Failed responses raise KapsuleError with status and detail.

Metadata

Release files for capsule-ai 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for capsule-ai 0.1.0
File	Size	Uploaded
capsule_ai-0.1.0.tar.gz	4.3 kB	Oct 2, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for capsule-ai 0.1.0
File	Interpreter	ABI	Platform	Reset
capsule_ai-0.1.0-py3-none-any.whl 4.5 kB Oct 2, 2026	Python 3	none	any	Details

Total release size: 8.8 kB

Release files / capsule_ai-0.1.0.tar.gz

Download URL	capsule_ai-0.1.0.tar.gz
Size	4.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`af68ab81d92e9433d85db7caaac17345309536779c7b12273f51a77c63c5c479`
BLAKE2b-256 checksum How to use checksums	`b1b4f9d874dc7a52473d83dd8c849621a27749509b3105bd37fc8ca173b787a1`
Upload date	Oct 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.10.12`

Release files / capsule_ai-0.1.0-py3-none-any.whl

Download URL	capsule_ai-0.1.0-py3-none-any.whl
Size	4.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`b6992ae75016efaae2a5721cf9c7859f782fb821b4ede37259d532996b2fe336`
BLAKE2b-256 checksum How to use checksums	`5ff6a849830d62e7e8a723479b94a4b63d1abb0a040de3aa500969cbd8bea176`
Upload date	Oct 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.10.12`