OpenSIN Documentation

Appearance

Global Brain & Neural-Bus ​

The persistent knowledge and communication layer for the entire OpenSIN-AI agent fleet.

Overview ​

The OpenSIN ecosystem uses two complementary systems for fleet-wide intelligence:

SystemPurposeRepository
Global Brain (PCPM)Persistent Code Plan Memory — cross-project knowledge, rules, plansglobal-brain
Neural-Bus (JetStream)Real-time agent-to-agent messaging via NATS JetStreamOpenSIN-Neural-Bus

Global Brain (PCPM) ​

The Persistent Code Plan Memory (PCPM) system ensures that knowledge, rules, and plans persist across all agent sessions and projects.

Key Features ​

  • sin-brain CLI — Add rules, sync knowledge, check Neural-Bus status
  • sin-brain MCP — Real-time rule management for agents (add_rule, sync_brain, list_global_rules)
  • Preview MCP — Opens images directly in macOS Preview.app (open_in_preview, open_image_in_preview)
  • Auto-Sync Hooks — After every OpenCode run, knowledge is automatically synced via sync-chat-turn
  • Bidirectional Sync — Global brain ↔ local project .pcpm/ directories

CLI Commands ​

bash
# Add a rule to global brain
node src/cli.js add-rule --text "Your rule" --priority -5 --scope global

# Sync after chat turn (runs automatically via afterRun hook)
node src/cli.js sync-chat-turn

# Check Neural-Bus status
node src/cli.js neural-bus-status

# Setup hooks in a project
node src/cli.js setup-hooks --project my-project --project-root /path/to/repo

MCP Tools ​

ToolServerDescription
add_rulesin-brain MCPAdd rules to global AGENTS.md and/or local .pcpm
sync_brainsin-brain MCPRun bidirectional sync between local and global brain
open_image_in_previewsin-brain MCPOpen an image file in macOS Preview.app
list_global_rulessin-brain MCPList all rules currently in the global brain
open_in_previewPreview MCPOpens an image file in Preview.app with validation

Project Brain Structure ​

Every project connected to the Global Brain has a .pcpm/ directory:

.pcpm/
├── knowledge-summary.json  # Global rules + project facts/mistakes/solutions
├── plan/
│   └── latest.json         # Current plan with step tracking
└── active-context.json     # Current goal state + forbidden strategies

Auto-Sync Integration ​

After every OpenCode run, the afterRun hook automatically executes:

bash
node "$BRAIN_CLI" sync-chat-turn 2>/dev/null

This ensures knowledge is never lost between sessions — all bug fixes, architectural decisions, and discovered patterns are persistently stored.

Neural-Bus (JetStream) ​

The OpenSIN-Neural-Bus is a NATS JetStream-based message bus connecting all A2A agents, OpenCode runtimes, and the Global Brain through a unified event system.

Architecture ​

OpenCode CLI / Agent Runtime
  ↓
OpenSinAgentRuntime (agentId, sessionId, bus)
  ↓
JetStream (nats://127.0.0.1:4222)
  ↓
Subjects: workflow.request, workflow.reply, agent.observation, agent.lesson
  ↓
Ouroboros Bridge → rememberLesson() / registerCapability()
  ↓
Global Brain (.pcpm/ → AGENTS.md → knowledge graph)

Core Exports ​

ExportLanguagePurpose
OpenCodeJetStreamClientTypeScriptNATS/JetStream client for OpenCode
OpenSinAgentRuntimeTypeScriptAgent runtime wrapper with publish/consume
SUBJECTSTypeScriptCanonical subject taxonomy
createEventEnvelopeTypeScriptValidated event envelopes
OuroborosMemoryPythonSQLite-backed memory store
OuroborosCLIPythonPython CLI for Ouroboros memory

Subject Taxonomy ​

SubjectDirectionPurpose
workflow.requestClient → ServerWork request to agent
workflow.replyServer → ClientAnswer/result
agent.observationAgent → BrainState report (boot, error, done)
agent.lessonAgent → BrainLearned lesson (written to brain memory)
agent.capabilityAgent → BrainNew capability registered

Durable Consumer Pattern ​

typescript
const worker = await runtime.consumeAssignedWork({
  subject: SUBJECTS.workflowRequest,
  stream: "OPENSIN_WORKFLOW_EVENTS",
  durableName: "issue-8-worker",  // Same name = resume after restart
  deliverPolicy: "all",
  ackWaitMs: 500,
}, async (event) => {
  // Process work
});

Lesson Publishing ​

typescript
await runtime.publishLessonLearned({
  context: "JetStream reconnect handling",
  lesson: "Reuse the same durable consumer name so restart recovery is automatic.",
  successRate: 1.0,
});
// → Automatically written to Global Brain via Ouroboros Bridge

Local Verification ​

bash
cd ~/dev/OpenSIN-Neural-Bus
docker compose up -d nats
npm install && npm test

Integration with OpenCode ​

Both systems are integrated into the global OpenCode configuration:

json
{
  "mcp": {
    "sin-brain": {
      "type": "local",
      "command": ["node", "/Users/jeremy/dev/global-brain/src/mcp/sin-brain-server.mjs"],
      "enabled": true
    },
    "sin-preview": {
      "type": "local",
      "command": ["node", "/Users/jeremy/dev/global-brain/src/mcp/preview-server.mjs"],
      "enabled": true
    }
  }
}