axisdream

Official TypeScript SDK for Axisdream — client for the Axisdream Context OS.

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

Install

npm install axisdream
# or
pnpm add axisdream
# or
bun add axisdream

Quickstart

import { Axisdream } from "axisdream";

// Reads AXISDREAM_API_KEY and AXISDREAM_BASE_URL from environment automatically
const cog = new Axisdream();
const space = await cog.space("my-agent");

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

// Search first for substantive context. Axisdream coordinates all retrieval layers.
const results = await space.retrieve("retry logic", {
  top_k: 10,         // final accepted context chunks (maximum 20)
  query_variants: [
    { query: "retry logic with backoff failures", kind: "rewrite" },
    { query: "a passage describing reliable retry behavior with backoff and jitter", kind: "hyde" },
    { query: "retry backoff jitter", kind: "exact" },
  ],
});
for (const item of results.results) {
  console.log(`${item.file_path}: ${item.score} (${item.source})`);
}

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

// Inspect structure only when a path or folder is specifically needed.
const files = await space.list("knowledge");
console.log(`${files.file_count} files`);

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

Works everywhere

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

API Reference

new Axisdream(config?)

Reads AXISDREAM_API_KEY from environment if apiKey not provided.

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

cog.space(nameOrId) → SpaceClient

| Method | Description | |---|---| | space.list(folder?) | List files in folder | | space.fetch(path) | Get one file | | space.retrieve(query, options?) | Ranked context discovery across semantic, lexical, and relationship signals | | space.add(path, content, bucket, topic, options?) | Create or replace one context file | | space.forget(path) | Delete one file from the space | | space.getTools() | Fetch the Platform's live MCP-compatible tool schemas |

add() parameters

space.add(
  "knowledge/retry.md",           // path
  "# Retry\nUse backoff...",      // content
  "knowledge",                    // bucket: "knowledge" | "memory" | "skills" | "state"
  "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

retrieve() options (enforced at backend). The backend coordinates the retrieval sources automatically and returns at most top_k accepted chunks:

space.retrieve("query", {
  top_k: 10,             // final accepted context chunks (1–20, default 10)
  bucket?: "knowledge" | "memory" | "skills" | "state",  // filter by bucket
  folder_path?: string, // restrict to folder
  query_variants: [      // exactly one rewrite, hyde, and exact probe
    { query: string, kind: "rewrite" | "exact" | "hyde" },
  ],
})

Examples:

// Adjust coverage while keeping the backend retrieval pipeline automatic
space.retrieve("query", { top_k: 10 })

// Multi-aspect retrieval: one call, bounded and deduplicated by Axisdream
space.retrieve("design the onboarding modal", {
  query_variants: [
    { query: "modal composition and hierarchy", kind: "rewrite" },
    { query: "accessible onboarding dialog behavior", kind: "exact" },
  ],
  top_k: 10,
})

Errors

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

try {
  await space.retrieve("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 uses baseUrl, then AXISDREAM_BASE_URL, then http://localhost:8000 for local development.