Getting started

SDKs and CLI

Use the SDKs when you want typed helpers and provider-friendly context builders. Use the CLI for local checks, scripted workflows, and integration smoke tests.

These coordinates are release candidates until the first public registry release is announced. The Python distribution is neutron-ai-sdk; its import remains neutron_ai.

Packages

Environment	Package	Primary use
TypeScript / JavaScript	`@neutron-ai/sdk`	Node apps, web backends, agent runtimes, MCP helpers.
CLI	`@neutron-ai/cli`	macOS, Windows, Linux, CI, and support workflows.
Python	`neutron-ai-sdk`	AI apps, notebooks, evaluation scripts, automation.
PHP	`neutron-ai/sdk`	Laravel, Symfony, WordPress, and custom PHP backends.
Go	`github.com/neutron-ai/neutron/packages/sdk-go`	Services, background jobs, and platform tools.
Rust	`neutron-ai`	Typed services and custom agent runtimes.

TypeScript

import { NeutronAIClient } from "@neutron-ai/sdk";

const client = new NeutronAIClient({
  baseUrl: process.env.NEUTRON_API_URL!,
  token: process.env.NEUTRON_API_TOKEN!,
  nucleusId: process.env.NEUTRON_NUCLEUS_ID!
});

await client.remember({
  scopeId: process.env.NEUTRON_SCOPE_ID!,
  type: "preference",
  text: "Prefers concise release notes with clear migration steps."
});

const context_pack = await client.agentContext({
  scopeIds: [process.env.NEUTRON_SCOPE_ID!],
  agentId: "agent_docs",
  task: "Draft an SDK migration note"
});

The TypeScript client also exposes typed intelligence facades:

await client.entities.upsert({
  scopeId: process.env.NEUTRON_SCOPE_ID!,
  id: "service_api",
  type: "service",
  name: "Decision API",
  attributes: { status: "operational" },
  confidence: 0.95,
  provenance: {
    sourceType: "database",
    sourceId: "service-catalogue",
    classification: "observed",
    recordedAt: Date.now(),
  },
});

const context = await client.context.build({
  scopeIds: [process.env.NEUTRON_SCOPE_ID!],
  task: "Assess the next API release",
  entities: [{ entityId: "service_api" }],
  tokenBudget: 4_000,
  includeContradictions: true,
  debug: true,
});

Available facades include memory, entities, graph, context, decisions, consequences, outcomes, learning, agents, snapshots, claims, contradictions, simulate, and search.

Python, PHP, Go, and Rust retain their current typed memory and consequence workflows. Use the authenticated REST routes for newer knowledge and decision operations until typed parity is documented.

CLI

npm install -g @neutron-ai/cli

export NEUTRON_API_URL="https://neutronai.dev/api"
export NEUTRON_API_TOKEN="<server-issued-token>"
export NEUTRON_NUCLEUS_ID="<nucleus-id>"
export NEUTRON_SCOPE_ID="<authorized-scope-id>"

neutron health
neutron remember --scope $NEUTRON_SCOPE_ID --type preference --text "Prefers short examples"
neutron recall --scope $NEUTRON_SCOPE_ID --query "documentation preferences"
neutron context --scope $NEUTRON_SCOPE_ID --task "Answer an SDK question"
neutron mcp-tools
neutron import-obsidian --vault ~/Documents/Obsidian/Product --scope kb:obsidian --privacy-class user_private --dry-run

PowerShell:

$env:NEUTRON_API_URL="https://neutronai.dev/api"
$env:NEUTRON_API_TOKEN="<server-issued-token>"
$env:NEUTRON_NUCLEUS_ID="<nucleus-id>"
$env:NEUTRON_SCOPE_ID="<authorized-scope-id>"

neutron health

Obsidian Vaults

Use the Obsidian importer when a local vault should become scoped agent memory.

neutron import-obsidian \
  --vault ~/Documents/Obsidian/Product \
  --scope kb:obsidian \
  --privacy-class user_private \
  --dry-run

neutron import-obsidian \
  --vault ~/Documents/Obsidian/Product \
  --scope kb:obsidian \
  --privacy-class user_private

The importer supports Markdown notes, JSON Canvas files, and Bases. It skips .obsidian configuration and stores note paths, tags, wikilinks, embeds, Canvas structure, and Base view names as metadata.

Python

import os

from neutron_ai import NeutronAIClient

client = NeutronAIClient(
    base_url="https://neutronai.dev/api",
    token=os.environ["NEUTRON_API_TOKEN"],
    nucleus_id=os.environ["NEUTRON_NUCLEUS_ID"],
)

client.remember({
    "scopeId": os.environ["NEUTRON_SCOPE_ID"],
    "type": "preference",
    "text": "Prefers short examples",
})

context_pack = client.agent_context({
    "scopeIds": [os.environ["NEUTRON_SCOPE_ID"]],
    "agentId": "agent_docs",
    "task": "Draft an SDK migration note",
})

PHP

use NeutronAI\NeutronAIClient;

$client = new NeutronAIClient(
    base_url: 'https://neutronai.dev/api',
    token: getenv('NEUTRON_API_TOKEN'),
    nucleus_id: getenv('NEUTRON_NUCLEUS_ID'),
);

$client->remember([
    'scopeId' => getenv('NEUTRON_SCOPE_ID'),
    'type' => 'preference',
    'text' => 'Prefers short examples',
]);

$context_pack = $client->agentContext([
    'scopeIds' => [getenv('NEUTRON_SCOPE_ID')],
    'agentId' => 'agent_docs',
    'task' => 'Draft an SDK migration note',
]);

Go

client, err := neutron.NewClient(neutron.Options{
    BaseURL: "https://neutronai.dev/api",
    Token: os.Getenv("NEUTRON_API_TOKEN"),
    NucleusID: os.Getenv("NEUTRON_NUCLEUS_ID"),
})
if err != nil {
    return err
}

_, err = client.Remember(ctx, map[string]any{
    "scopeId": os.Getenv("NEUTRON_SCOPE_ID"),
    "type": "preference",
    "text": "Prefers short examples",
})
if err != nil {
    return err
}

contextPack, err := client.AgentContext(ctx, map[string]any{
    "scopeIds": []string{os.Getenv("NEUTRON_SCOPE_ID")},
    "agentId": "agent_docs",
    "task": "Draft an SDK migration note",
})
if err != nil {
    return err
}
_ = contextPack

Rust

use neutron_ai::{ClientOptions, NeutronAIClient};
use serde_json::json;

let client = NeutronAIClient::new(ClientOptions {
    base_url: "https://neutronai.dev/api".to_string(),
    token: Some(std::env::var("NEUTRON_API_TOKEN").expect("NEUTRON_API_TOKEN is required")),
    nucleus_id: Some(std::env::var("NEUTRON_NUCLEUS_ID").expect("NEUTRON_NUCLEUS_ID is required")),
    tenant_id: None,
})?;

client.remember(json!({
    "scopeId": std::env::var("NEUTRON_SCOPE_ID")?,
    "type": "preference",
    "text": "Prefers short examples"
})).await?;

let context_pack = client.agent_context(json!({
    "scopeIds": [std::env::var("NEUTRON_SCOPE_ID")?],
    "agentId": "agent_docs",
    "task": "Draft an SDK migration note"
})).await?;

MCP

Remote MCP lets compatible agent hosts call Neutron memory and intelligence tools directly.

import { createNeutronMcpServerUrl, createOpenAIMcpTool } from "@neutron-ai/sdk";

const neutron_memory = createOpenAIMcpTool({
  serverUrl: createNeutronMcpServerUrl("https://mcp.neutronai.dev"),
  serverLabel: "neutron_memory",
  allowedTools: ["memory_agent_context", "memory_recall"],
  requireApproval: "never"
});

Keep write-capable tools disabled unless the host is trusted to create, update, or delete knowledge, propose decisions, record outcomes, or run simulations within its authorised Scopes.

API

Sandbox testing