cogspace 0.4.0

Official Cogspace SDK — add a knowledge layer to any AI agent

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)
os.environ["COGSPACE_API_KEY"] = "cs-..."

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
    results = await space.search("retry logic", limit=5)
    for item in results.results:
        print(f"{item.path}: {item.score:.2f}")

    # 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("retry logic", limit=5)
    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.

Method	Description
cog.space(name_or_id)	Get a space client by name or ID
cog.list_spaces()	List all your spaces
cog.create_space(name)	Create a new space

SpaceClient

Method	Args	Description
space.list(folder)	folder=""	List files in folder
space.retrieve(path)	path	Get one file with content + metadata
space.search(query, limit, layer)	limit=10, layer=None	Search all layers
space.add(path, content, layer, topic, confidence, relates_to)	see below	Add/update knowledge
space.forget(path)	path	Delete from all layers

add() parameters

Param	Type	Required	Description
path	str	yes	File path (e.g. "expertise/retry.md")
content	str	yes	Markdown content
layer	str	yes	"expertise", "memory", or "root"
topic	str	yes	Category/topic
confidence	float	no	0.0-1.0, default 0.9
relates_to	list[str]	no	Related file names

Layers

Layer	Use for
expertise	Knowledge, patterns, guides, reference material
memory	Agent memory, user preferences, session notes
root	General knowledge that doesn't fit elsewhere

Limits

• search(limit=...) — max 100 results per call
• forget() — single file per call

Errors

from cogspace.exceptions import AuthError, NotFoundError, RateLimitError, LimitExceededError

try:
    results = await space.search("query", limit=200)
except LimitExceededError:
    print("Limit must be <= 100")
except AuthError:
    print("Invalid API key")
except NotFoundError:
    print("Space not found")

Get an API key

Sign in at platform.cogspace.ai → Settings → API keys → Create key.