cogspace 0.1.0

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

cogspace

Official Python SDK for Cogspace — add a persistent knowledge layer to any AI agent.

Install

pip install cogspace

Quickstart

from cogspace import Cogspace

cog = Cogspace(api_key="cs-...")

# Get a space-scoped client
space = cog.space("my-agent")

# Search
results = space.search("retry logic with backoff")
for r in results.results:
    print(r.file_path, r.score)

# Write knowledge
space.write("expertise/retry.md", """
# Retry patterns
Always use exponential backoff with jitter.
""")

# Read the hot layer (always-injected context)
context = space.hot_layer()

# Memory
space.write_memory("Currently working on the payment service refactor.")
memory = space.read_memory()

Async

from cogspace import AsyncCogspace

async def main():
    cog = AsyncCogspace(api_key="cs-...")
    space = await cog.space("my-agent")
    results = await space.search("retry logic")
    await cog.aclose()

Or use as a context manager:

async with AsyncCogspace(api_key="cs-...") as cog:
    space = await cog.space("my-agent")
    await space.write("expertise/notes.md", "...")

API Reference

Cogspace(api_key, base_url, timeout, max_retries)

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

SpaceClient

Method	Description
space.search(query, mode, top_k, layer)	Hybrid / vector / keyword search
space.read(path)	Read a file by path
space.write(path, content, metadata)	Write or update a file
space.list(folder)	List files in a folder
space.read_memory()	Read memory.md
space.write_memory(content, confidence)	Update memory.md
space.read_context()	Read memory/user/ context files
space.hot_layer()	Get full hot layer injection string
space.graph_traverse(path, depth, rel_type)	Traverse knowledge graph
space.health()	Space health and storage stats

Errors

All exceptions inherit from CogspaceError:

from cogspace.exceptions import AuthError, NotFoundError, RateLimitError

try:
    space.search("query")
except AuthError:
    print("Invalid API key")
except NotFoundError:
    print("Space not found")

Get an API key

Sign in at platform.cogspace.ai, go to Settings → API keys, and create a key.