Continuity Engine

API Reference

Complete API documentation for integrating with the Continuity Engine programmatically.

Authentication

All API endpoints require authentication. Include your session token in the request headers. Workspace-scoped endpoints also require workspace membership.

Context Endpoints

Get Conversation Context

Retrieves the current context state for a conversation, including the rolling summary, pinned memory, and metadata.

Requesthttp

GET /api/context?conversationId={conversationId}

Responsejson

{
  "success": true,
  "context": {
    "rollingSummary": {
      "goals": ["Build a REST API for user management"],
      "decisions": [
        {
          "id": "dec_1",
          "decision": "Use PostgreSQL",
          "reason": "Need strong consistency",
          "timestamp": "2024-01-15T10:30:00Z"
        }
      ],
      "requirements": ["Support 10k concurrent users"],
      "currentPlan": ["Design schema", "Implement endpoints"],
      "openQuestions": ["Caching strategy?"],
      "definitions": {
        "user": "A registered customer with verified email"
      },
      "importantReferences": [
        { "type": "file", "value": "schema.prisma", "label": "DB Schema" }
      ],
      "stylePreferences": {},
      "lastUpdated": "2024-01-15T10:30:00Z",
      "version": 3
    },
    "pinnedMemory": [
      {
        "id": "pin_1",
        "messageId": "msg_123",
        "content": "API must use JWT authentication",
        "category": "requirement",
        "pinnedAt": "2024-01-15T09:00:00Z"
      }
    ],
    "metadata": {
      "totalTokens": 15000,
      "compressedTokens": 12000,
      "preservationRatio": 80,
      "lastCompactionAt": "2024-01-15T10:30:00Z",
      "recentMessageCount": 20
    }
  }
}

Get Rolling Summary Only

Retrieves just the rolling summary without pinned memory or metadata.

Requesthttp

GET /api/context/summary?conversationId={conversationId}

Responsejson

{
  "success": true,
  "summary": {
    "goals": [...],
    "decisions": [...],
    "requirements": [...],
    "currentPlan": [...],
    "openQuestions": [...],
    "definitions": {...},
    "importantReferences": [...],
    "stylePreferences": {...},
    "lastUpdated": "2024-01-15T10:30:00Z",
    "version": 3
  }
}

Compact Context

Triggers a manual compaction of the conversation context.

Requesthttp

POST /api/context/compact
Content-Type: application/json

{
  "conversationId": "conv_123",
  "level": "light"  // "light" | "deep" | "aggressive"
}

Responsejson

{
  "success": true,
  "result": {
    "success": true,
    "previousTokenCount": 15000,
    "newTokenCount": 10000,
    "tokensRemoved": 5000,
    "summaryUpdated": true
  }
}

Pinning Endpoints

Pin a Message

Pins a message to preserve it in the context.

Requesthttp

POST /api/context/pin/{conversationId}
Content-Type: application/json

{
  "messageId": "msg_123",
  "category": "decision"  // optional: "decision" | "requirement" | "reference" | "other"
}

Responsejson

{
  "success": true,
  "pinnedItem": {
    "id": "pin_abc",
    "messageId": "msg_123",
    "content": "We decided to use PostgreSQL...",
    "category": "decision",
    "pinnedAt": "2024-01-15T11:00:00Z"
  }
}

Unpin a Message

Removes a pin from a message.

Requesthttp

DELETE /api/context/pin/{conversationId}?messageId={messageId}

Responsejson

{
  "success": true
}

Exclusion Endpoints

Exclude/Include Message

Marks a message to be excluded from (or included in) the rolling summary.

Requesthttp

PATCH /api/context/exclude/{conversationId}/{messageId}
Content-Type: application/json

{
  "exclude": true  // true to exclude, false to include
}

Responsejson

{
  "success": true
}

User Memory Endpoints

List User Memory

Retrieves all user memory items, optionally filtered by type.

Requesthttp

GET /api/memory?workspaceId={workspaceId}&type={type}

// type is optional: "preference" | "fact" | "constraint" | "definition"

Responsejson

{
  "success": true,
  "memories": [
    {
      "id": "mem_1",
      "type": "preference",
      "key": "coding_style",
      "content": "I prefer functional programming patterns"
    },
    {
      "id": "mem_2",
      "type": "fact",
      "key": "project_stack",
      "content": "Next.js 14 with TypeScript and Tailwind"
    }
  ]
}

Create User Memory

Creates a new user memory item.

Requesthttp

POST /api/memory
Content-Type: application/json

{
  "type": "preference",
  "key": "coding_style",
  "content": "I prefer functional programming patterns with TypeScript",
  "workspaceId": "ws_123"  // optional
}

Responsejson

{
  "success": true,
  "memory": {
    "id": "mem_abc",
    "type": "preference",
    "key": "coding_style",
    "content": "I prefer functional programming patterns with TypeScript"
  }
}

Update User Memory

Updates an existing user memory item.

Requesthttp

PATCH /api/memory/{memoryId}
Content-Type: application/json

{
  "content": "Updated content here",
  "isActive": true  // optional: deactivate without deleting
}

Responsejson

{
  "success": true,
  "memory": {
    "id": "mem_abc",
    "type": "preference",
    "key": "coding_style",
    "content": "Updated content here"
  }
}

Delete User Memory

Permanently deletes a user memory item.

Requesthttp

DELETE /api/memory/{memoryId}

Responsejson

{
  "success": true
}

React Hook

For client-side integration, use the useConversationContext hook:

Usagetypescript

import { useConversationContext } from "@/lib/continuity-engine/client";

function ChatInterface({ conversationId, workspaceId }) {
  const context = useConversationContext({
    conversationId,
    workspaceId,
    enabled: true,
  });

  // Access state
  const { summary, pinnedMemory, metadata, isLoading, error } = context;

  // UI controls
  const { isDrawerOpen, openDrawer, closeDrawer } = context;

  // Actions
  const handlePin = async (messageId: string) => {
    await context.pinMessage(messageId, "decision");
  };

  const handleUnpin = async (messageId: string) => {
    await context.unpinMessage(messageId);
  };

  const handleExclude = async (messageId: string, exclude: boolean) => {
    await context.excludeMessage(messageId, exclude);
  };

  const handleCompact = async () => {
    await context.compact("light");
  };

  return (
    <>
      <ContextIndicator
        metadata={metadata}
        pinnedCount={pinnedMemory.length}
        onClick={openDrawer}
      />

      <SummaryDrawer
        isOpen={isDrawerOpen}
        onClose={closeDrawer}
        summary={summary}
        pinnedMemory={pinnedMemory}
        metadata={metadata}
        onCompact={handleCompact}
        onUnpin={handleUnpin}
        isCompacting={context.isCompacting}
      />
    </>
  );
}

Hook Return Type

Type Definitiontypescript

interface UseConversationContextReturn {
  // State
  summary: RollingSummary | null;
  pinnedMemory: PinnedMemoryItem[];
  metadata: ContextMetadata | null;
  isLoading: boolean;
  error: Error | null;
  isCompacting: boolean;

  // UI Controls
  isDrawerOpen: boolean;
  openDrawer: () => void;
  closeDrawer: () => void;

  // Actions
  refresh: () => Promise<void>;
  pinMessage: (messageId: string, category?: PinnedMemoryCategory) => Promise<boolean>;
  unpinMessage: (messageId: string) => Promise<boolean>;
  excludeMessage: (messageId: string, exclude: boolean) => Promise<boolean>;
  compact: (level?: CompactionLevel) => Promise<boolean>;
}

TypeScript Types

All types are exported from @/lib/continuity-engine/client:

Type Exportstypescript

// Core types
export type {
  RollingSummary,
  Decision,
  Reference,
  StylePreferences,
  PinnedMemoryItem,
  PinnedMemoryCategory,
  UserMemoryItem,
  MemoryType,
  ContextMetadata,
  ContextPack,
  CompactionLevel,
  CompactionResult,
} from "./types";

// Hook
export { useConversationContext } from "./useConversationContext";

// Constants
export { CONTINUITY_CONFIG, FEATURE_FLAGS } from "./constants";

Error Handling

All endpoints return a consistent error format:

Error Responsejson

{
  "success": false,
  "error": "Descriptive error message"
}

// HTTP Status Codes:
// 400 - Bad Request (invalid parameters)
// 401 - Unauthorized (missing/invalid auth)
// 403 - Forbidden (no workspace access)
// 404 - Not Found (conversation/message doesn't exist)
// 500 - Internal Server Error

Rate Limiting

API endpoints are rate-limited. The compact endpoint has stricter limits due to its computational cost. Expect 429 responses if limits are exceeded.

Auto-Compaction Plans & Pricing