cogspace

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

Available on npm as cogspace — the same package name as the Python SDK.

Install

npm install cogspace
# or
pnpm add cogspace
# or
bun add cogspace

Quickstart

import { Cogspace } from "cogspace";

// Reads COGSPACE_API_KEY from environment automatically
const cog = new Cogspace();
const space = await cog.space("my-agent");

// See what exists
const files = await space.list("expertise");
console.log(`${files.file_count} files`);

// Add knowledge
await space.add(
  "expertise/retry.md",
  "# Retry Patterns\nUse exponential backoff with jitter.",
  "expertise",
  "retry-patterns",
  { confidence: 0.95 }
);

// Search (vectors + BM25 + knowledge graph, per-source limits)
const results = await space.searchHybrid("retry logic", {
  vector_limit: 10,  // max vector results
  bm25_limit: 10,    // max keyword results
  kg_limit: 5,       // max graph neighbors per result
});
for (const item of results.results) {
  console.log(`${item.file_path}: ${item.score} (${item.source})`);
}

// Retrieve a file
const file = await space.retrieve("expertise/retry.md");
console.log(file.content);

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

Works everywhere

Native fetch — no dependencies. Works in Node 18+, Deno, Bun, Edge, browser.

API Reference

new Cogspace(config?)

Reads COGSPACE_API_KEY from environment if apiKey not provided.

| Option | Default | Description | |---|---|---| | apiKey | env COGSPACE_API_KEY | Your API key | | baseUrl | http://localhost:8000 | Backend URL | | timeout | 30000 | Request timeout (ms) | | maxRetries | 3 | Retries on 429/5xx |

cog.space(nameOrId) → SpaceClient

| Method | Description | |---|---| | space.list(folder?) | List files in folder | | space.retrieve(path) | Get one file | | space.searchHybrid(query, options?) | Unified search: vectors + BM25 + KG | | space.add(path, content, layer, topic, options?) | Add/update knowledge | | space.forget(path) | Delete from all layers | | space.getTools() | Fetch the Platform's live MCP-compatible tool schemas |

add() parameters

space.add(
  "expertise/retry.md",           // path
  "# Retry\nUse backoff...",      // content
  "expertise",                    // layer: "expertise" | "memory" | "root"
  "retry-patterns",               // topic
  {
    confidence: 0.95,             // 0.0-1.0, default 0.9
    related: ["error.md"],        // canonical related files
    relates_to: ["error.md"],     // backward-compatible alias
  }
)

Search limits

searchHybrid() options (enforced at backend):

space.searchHybrid("query", {
  vector_limit: 100,    // max vector results (0–100, default 100)
  bm25_limit: 100,      // max keyword results (0–100, default 100)
  kg_limit: 100,        // max graph neighbors per result (0–100, default 100)
  layer?: "expertise" | "memory" | "root",  // filter by layer
  folder_path?: string, // restrict to folder
})

Examples:

// Pure vector search (skip BM25)
space.searchHybrid("query", { bm25_limit: 0 })

// Pure keyword search (skip vectors)
space.searchHybrid("query", { vector_limit: 0 })

// Skip graph enrichment
space.searchHybrid("query", { kg_limit: 0 })

// Fine-grained control
space.searchHybrid("query", { vector_limit: 5, bm25_limit: 3, kg_limit: 1 })

Errors

import { AuthError, NotFoundError, RateLimitError } from "cogspace";

try {
  await space.searchHybrid("query");
} catch (err) {
  if (err instanceof AuthError) console.error("Invalid API key");
  if (err instanceof NotFoundError) console.error("Space not found");
  if (err instanceof RateLimitError) console.error("Rate limited");
}

Local-first note

The TypeScript SDK defaults to http://localhost:8000. If backend auth is disabled locally, any non-empty COGSPACE_API_KEY works.