Developers Beta

Choose Your Integration

Cosinia supports two integration paths depending on your use case.

SDK (Recommended)

Unified interface for natural language and structured semantic queries

Cosinia SDK allows you to interact with deterministic semantic memory using either natural language or structured JSON — through a single interface.

Use text for simplicity, or structured input for deterministic control.

Install

npm install cosinia

Quick Start

1. Create a world
2. Observe facts into memory
3. Recall structured answers

Two Ways to Use Cosinia

• Natural Language (English for now) — simple and flexible
• Structured Query — precise and deterministic

Observe Knowledge

Natural language:

Ray owns a house

Structured semantic input:

{
  "events": [
    {
      "process": "asymmetric_relation",
      "roles": {
        "role_owner": ["ray"],
        "role_owned": ["house"]
      }
    }
  ]
}

Step 1 — Create a world

curl https://api.cosinia.com/worlds \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "name": "worldX"
}'

Step 2 — Observe knowledge

curl https://api.cosinia.com/observe \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "world_id": "worldX",
  "text": "Ray owns a house"
}'

Recall Knowledge

Natural language:

Does Ray own a house?

Structured deterministic query:

{
  "mode": "recall",
  "extensions": {
    "process_family": "ASYMMETRIC_RELATION",
    "query_roles": {
      "role_owner": ["ray"]
    },
    "target_role": "role_owned"
  }
}

curl https://api.cosinia.com/recall \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "world_id": "worldX",
  "query": "Does Ray own a house?"
}'

SDK Example

import Cosinia from "cosinia"

const cosinia = new Cosinia({
  apiKey: "YOUR_API_KEY",
  worldId: "worldX"
})

// ─────────────────────────
// 1. OBSERVE (TEXT)
// ─────────────────────────
await cosinia.observe("Ray owns a house")

// ─────────────────────────
// 2. OBSERVE (STRUCTURED)
// ─────────────────────────
await cosinia.observe({
  events: [
    {
      process: "asymmetric_relation",
      roles: {
        role_owner: ["ray"],
        role_owned: ["house"]
      }
    }
  ]
})

// ─────────────────────────
// 3. RECALL (TEXT)
// ─────────────────────────
const res1 = await cosinia.recall(
  "Does Ray own a house?"
)

// ─────────────────────────
// 4. RECALL (STRUCTURED)
// ─────────────────────────
const res2 = await cosinia.recall({
  mode: "recall",
  extensions: {
    process_family: "ASYMMETRIC_RELATION",
    query_roles: {
      role_owner: ["ray"]
    },
    target_role: "role_owned"
  }
})

console.log(res1)
console.log(res2)

Direct JSON API

Cosinia exposes a deterministic JSON protocol for direct API integration. This gives full control over semantic ingestion.

• Minimum — simple usage
• Extended — full semantic control

Minimum Observe

{
  "mode": "observe",
  "world_id": "worldX",
  "events": [
    {
      "process": "own",
      "participants": [
        { "entity": "Ray" },
        { "entity": "house" }
      ]
    }
  ]
}

Extended Observe

Developers describe meaning and conditions — Cosinia assigns identity, time, and truth.

Response Example

{
  "query": "Does Ray own a house?",
  "relations": [
    {
      "subject": "ray",
      "relation": "own",
      "object": "house",
      "confidence": 0.99
    }
  ],
  "belief": {
    "value": true,
    "confidence": 0.99,
    "stability": 1
  }
}

Cosinia answers queries using deterministic semantic reasoning, not vector similarity or LLM hallucination.

Core Concepts

• World — an isolated semantic universe
• Observe — ingest structured knowledge into memory
• Recall — retrieve deterministic semantic answers
• Belief — computed truth from observations

Execution Model

Recall is executed inside a secure enclave.

• No database access during execution
• No network access during execution
• Deterministic, snapshot-based compute

Only the result leaves the enclave — nothing else.

API Endpoints

• /observe
• /recall
• /worlds
• /api-keys

Getting an API Key

Create an account and generate your API key from the dashboard.