neuroarch

Current release: NeuroArch 0.2.0 — Cognitive Observability

JavaScript/TypeScript SDK and CLI for NeuroArch — A Recursive Cognitive Closure Architecture for Persistent Local Agents.

Author: Yan Desbiens (AI Warlord)
License: MIT

What Is NeuroArch

NeuroArch is a 26-module autonomous cognitive layer that runs inside a local AI agent between user sessions. It maintains beliefs, dreams, goals, predictions, experiments, and attention scoring — all in local SQLite with no cloud dependency.

This package is the JavaScript client SDK for the NeuroArch HTTP API.

NeuroArch 0.2.0 — Cognitive Observability

This release makes the existing cognitive layer inspectable, explainable, exportable, and self-auditing. It adds health checks, belief provenance, unified timeline views, source-diversity scoring, safe public exports, and a single audit command without adding new cognitive subsystems.

Requirements

• Node.js ≥ 18
• A running NeuroArch API server (Python, see below)

Install

npm install neuroarch
# or globally for the CLI
npm install -g neuroarch

Start the API server

# from the hermes-agent repo
python -m memory.api_server

# custom port or DB path
python -m memory.api_server --port 7331 --db ~/.hermes/cognitive_memory.sqlite

Set NEUROARCH_DB env var to point at your cognitive_memory.sqlite.

CLI

neuroarch stats
neuroarch health
neuroarch doctor
neuroarch doctor --json
neuroarch audit --markdown
neuroarch beliefs --limit=20 --status=active
neuroarch belief explain <belief_id>
neuroarch belief diversity <belief_id>
neuroarch timeline --limit=50
neuroarch diversity --json
neuroarch export --format=markdown --out=./neuroarch-export.md
neuroarch beliefs --source=dream_crystallization --min_confidence=0.8
neuroarch goals --status=active
neuroarch dreams --limit=10 --min_importance=0.7
neuroarch memories --search=Hermes
neuroarch attention
neuroarch predictions --status=PENDING
neuroarch experiments --status=completed
neuroarch research --status=done

Override the server URL:

NEUROARCH_URL=http://192.168.1.10:7331 neuroarch stats

SDK

import { NeuroArch } from 'neuroarch';

const client = new NeuroArch({ baseUrl: 'http://127.0.0.1:7331' });

// System overview
const s = await client.stats();
console.log(`${s.beliefs_active} beliefs, ${s.idle_cycles} idle cycles`);

// Top beliefs by confidence
const beliefs = await client.beliefs({ limit: 10, min_confidence: 0.8 });
for (const b of beliefs) {
  console.log(`[${b.confidence.toFixed(2)}] ${b.statement}`);
}

// Recent dreams
const dreams = await client.dreams({ limit: 5, min_importance: 0.7 });

// Active goals
const goals = await client.goals({ status: 'active' });

// Search memories
const mems = await client.memories({ search: 'Hermes', limit: 20 });

// Attention targets
const targets = await client.attention();

API Reference

new NeuroArch(config?)

| Option | Type | Default | |--------|------|---------| | baseUrl | string | http://127.0.0.1:7331 |

Methods

| Method | Returns | |--------|---------| | health() | { status, version, db } | | doctor() | DoctorReport | | audit() | AuditReport | | stats() | Stats | | beliefs(opts?) | Belief[] | | belief(id) | Belief | | beliefExplanation(id) | BeliefExplanation | | beliefDiversity(id) | DiversityScore | | timeline(opts?) | TimelineEvent[] | | diversity() | DiversityDashboard | | exportReport(opts?) | string | | memories(opts?) | Memory[] | | goals(opts?) | Goal[] | | dreams(opts?) | Dream[] | | predictions(opts?) | Prediction[] | | experiments(opts?) | Experiment[] | | research(opts?) | Research[] | | attention() | AttentionTarget[] |

Full TypeScript types exported from neuroarch.

REST API Endpoints

The Python server exposes:

GET /health
GET /doctor
GET /audit
GET /stats
GET /beliefs          ?status=active&limit=50&source=X&min_confidence=0.0
GET /beliefs/:id
GET /beliefs/:id/explain
GET /beliefs/:id/diversity
GET /timeline         ?limit=100&type=belief,dream&since=TS
GET /diversity
GET /export           ?format=json|markdown|html&sections=beliefs,dreams
GET /memories         ?limit=50&search=X
GET /goals            ?limit=50&status=active
GET /dreams           ?limit=50&min_importance=0.0
GET /predictions      ?limit=50&status=PENDING
GET /experiments      ?limit=50&status=completed
GET /research         ?limit=50&status=done
GET /attention

All responses are JSON. CORS is open (*).