Neura SDK (neura-os)

The official Node.js & TypeScript SDK for Neura, the AI Personal Operating System. This SDK provides a typed interface to interact with the Neura Control Plane, Memory System, and Decision Engine.

Installation

npm install neura-os

Usage

Initialization

import { NeuraClient } from 'neura-os';

const client = new NeuraClient({
    apiKey: process.env.NEURA_API_KEY, // Optional if set in env
    endpoint: 'https://app.neura-os.com' // Optional, defaults to production
});

1. Registration (Identity)

Register a new agent or client to get an API Key.

const auth = await client.auth.register({
    org_id: 'my-org',
    name: 'my-agent',
    permissions: ['memory.read', 'decision.request']
});

console.log(`New API Key: ${auth.api_key}`);

2. Memory System

Store and retrieve memories. Neura handles semantic indexing automatically.

Store Memory:

await client.memory.store({
    content: "User prefers summary reports over detail.",
    type: "semantic",
    metadata: { source: "user_interview" }
});

Search Memory:

const results = await client.memory.search({
    query: "report preferences",
    limit: 5
});

3. Decisions (Control Plane)

Request permission to perform actions. Features deterministic policy enforcement.

const decision = await client.decide({
    intent: "deploy_production",
    actor: { type: "user", id: "dev-123" },
    resource: { type: "environment", id: "prod" },
    context: { branch: "main" }
});

if (decision.outcome === 'ACT') {
    // Perform action
} else if (decision.outcome === 'ESCALATE') {
    // Wait for human approval
    const finalDecision = await client.waitForDecision(decision.id);
    if (finalDecision.outcome === 'ACT') {
        // Perform action
    }
}

4. Validation (Dry Run)

Check if an action would be allowed without recording it.

const check = await client.validate({
    intent: "delete_database",
    actor: { type: "service", id: "cleanup-bot" },
    resource: { type: "db", id: "users" }
});

console.log(check.would_allow); // false