cogspace

Official Python SDK for Cogspace — persistent knowledge layer for AI agents.

Published on PyPI as cogspace.

Install

pip install cogspace

Quickstart

import asyncio
import os
from cogspace import AsyncCogspace

# Set your API key (or pass api_key= directly).
# In local dev with backend auth disabled, any non-empty value works.
os.environ["COGSPACE_API_KEY"] = "local-dev-token"

async def main():
    cog = AsyncCogspace()
    space = await cog.space("my-agent")

    # See what exists
    files = await space.list("expertise")
    print(f"Files: {files.file_count}")

    # Add knowledge
    await space.add(
        path="expertise/retry.md",
        content="# Retry Patterns\nUse exponential backoff with jitter.",
        layer="expertise",
        topic="retry-patterns",
        confidence=0.95,
    )

    # Search (vectors + BM25 + knowledge graph, per-source limits)
    results = await space.search_hybrid(
        "retry logic",
        vector_limit=10,  # max vector results
        bm25_limit=10,    # max keyword results
        kg_limit=5,       # max graph neighbors per result
    )
    for item in results.results:
        print(f"{item.file_path}: {item.score:.2f} ({item.source})")

    # Retrieve a file
    file = await space.retrieve("expertise/retry.md")
    print(file.content)

    # Delete
    await space.forget("expertise/retry.md")

    await cog.aclose()

asyncio.run(main())

Sync client

from cogspace import Cogspace

with Cogspace() as cog:
    space = cog.space("my-agent")
    files = space.list("expertise")
    results = space.search_hybrid("retry logic", vector_limit=10, bm25_limit=10)
    space.add(
        path="expertise/retry.md",
        content="# Retry Patterns\n...",
        layer="expertise",
        topic="retry-patterns",
    )
    space.forget("expertise/retry.md")

API Reference

Cogspace(api_key, base_url, timeout, max_retries)

Reads COGSPACE_API_KEY from environment if api_key not provided. Defaults to http://localhost:8000 for local development.

SpaceClient

add() parameters

Layers

Search limits

search_hybrid() parameters (enforced at backend):

Examples:

# Pure vector search (skip BM25)
results = await space.search_hybrid("query", bm25_limit=0)

# Pure keyword search (skip vectors)
results = await space.search_hybrid("query", vector_limit=0)

# Skip graph enrichment
results = await space.search_hybrid("query", kg_limit=0)

# Fine-grained control
results = await space.search_hybrid("query", vector_limit=5, bm25_limit=3, kg_limit=1)

Errors

from cogspace.exceptions import AuthError, NotFoundError, RateLimitError

try:
    results = await space.search_hybrid("query")
except AuthError:
    print("Invalid API key")
except NotFoundError:
    print("Space not found")
except RateLimitError:
    print("Rate limited, retry later")

Local-first note

The Python SDK is local-first by default:

• Default base URL: http://localhost:8000
• Space lookup accepts either a space name or a space ID
• If backend auth is disabled locally, use any non-empty COGSPACE_API_KEY