Multi-Agent Orchestration, Permissions-based MCP Server Broker, Context Continuity Across Sessions¶

An open-source agent runtime, built for engineers who ship.

Neuralgentics is the harness for AI agents - the execution environment, permission broker, and persistent memory that turns a language model into a reliable, debuggable, and trustworthy agent.

What is a harness? A harness provides the structural scaffolding that a raw model lacks. It wraps the LLM with specific prompts, tools, context, and strict permissions, ensuring the agent operates within defined boundaries and maintains continuity across sessions.

23 specialist agent roles, a trust-scored memory engine, and a permissions-based tool broker -- all packaged as a 340KB OpenCode plugin plus a 3-service container stack. No cloud account, no telemetry, no vendor lock-in. You run it on your machine; it remembers what your agents did; it stops them from doing things they shouldn't.

Install in seconds:

npx @veedubin/neuralgentics --init && opencode

Latest: v0.9.4 ships an npx --init bootstrapper that replaces the old curl-bash installer, plus a hardened container setup that won't touch existing .env files or running containers.

Get Started →

The Problem¶

Generic LLM coding agents have no persistent memory, no concept of role-based authority, and a single bloated context window. They forget Monday on Friday. Every agent sees every tool -- no roles, no scoped permissions, no audit trail. Prompts fight for the same slot, so you re-explain the project every session, or ship bugs the agent invented because it had no record of what failed.

What Neuralgentics Is¶

Neuralgentics replaces one "do-it-all" bot with structured, role-based orchestration. Twenty-three specialist agents -- architect, coder, tester, git, and more -- each receive only the tools their role authorizes and only the context their task requires.

Every decision lands in PostgreSQL + pgvector with trust scoring. Successful patterns get promoted; failed approaches decay and fade. The MCP broker gates every tool call against the agent's role, cutting token overhead by up to 95%. Context survives sessions through L0/L1/L2 tiered loading -- a new agent picks up where the last one left off.

Agent prompts are ~200 tokens each. State lives in memory, not in the prompt. Ships as a 340KB npm plugin + 3 Docker containers (Postgres 18 + Python gRPC sidecar + Go JSON-RPC backend). Open-source under the MIT License.

How It Works¶

    USER PROMPT
         │
         ▼
  ╔══════════════════╗
  ║   THOUGHT CHAIN  ║ ◄── Logged to memoryManager
  ╚══════════════════╝
         │
         ▼
  ╔══════════════════╗
  ║ TASK DECOMPOSE   ║ ◄── Create Kanban cards
  ╚══════════════════╝
         │
         ▼
  ╔══════════════════╗
  ║ ROUTE MATRIX     ║ ◄── Select specialist agent
  ╚══════════════════╝
         │
         ▼
  ╔══════════════════╗
  ║ CONTEXT PACKAGE  ║ ◄── Fetch L0/L1 memory
  ╚══════════════════╝
         │
         ▼
  ╔══════════════════╗
  ║    TASK() CALL   ║ ◄── Dispatch to agent
  ╚══════════════════╝
         │
         ▼
    [ SPECIALIST AGENT ]

A task enters the orchestrator, gets routed to a specialist, who calls the broker for tools, who checks RBAC, who executes -- and every decision lands in the trust-scored memory store. Full details at Dispatch Flow.

Features in Depth¶

The rest of this page walks through each major subsystem, with a small mockup showing what the feature looks like in practice. MOCKUPs are Unicode terminal drawings -- they show the real shape of the UI, not real screenshots.

Memory Engine -- Trust-Scored, Self-Decaying¶

• Harness-grade reliability - every tool call goes through the broker; every memory write is trust-scored; every permission is enforced at the code layer, not in the prompt.
• Memory Engine - Every decision an agent makes lands in PostgreSQL + pgvector with a trust score (default 0.5). Successful patterns get promoted; failed approaches decay and fade. The system is honest about what worked.

The memory store is pgvector-backed, so semantic search works the way you'd expect: "show me every dispatch that hit a build failure" returns similar past dispatches, ranked by trust. Trust is a first-class column, not a side table.

    MEMORY INSPECTOR  ·  query: "broker rbac dispatch"  ·  results: 4
    ─────────────────────────────────────────────────────────────────
    ID        TRUST   DECAY/DAY   USED   AGE     CONTENT
    a1b2c3..  0.91    0.01        17     12d     "Architect designs before
                                                  coder builds (Rule 1)"
    e5f6g7..  0.85    0.02        9      3d      "RBAC matrix: 23 roles x
                                                  7 restricted servers"
    i9j0k1..  0.62    0.08        2      1d      "MCP broker proxy is shared
                                                  across servers, do NOT
                                                  Stop() on deregister"
    m3n4o5..  0.42    0.05        1      2h      "Tested with fixture db,
                                                  weak signal, decay fast"
    ─────────────────────────────────────────────────────────────────
    Trust:  ● active (>0.5)   ○ fading (<0.5)   ∅ archived (<0.2)

See Memory System Reference for the trust engine, decay math, and embedding strategy.

MCP Broker -- RBAC-Gated Tool Calls¶

Every tool call goes through a broker that checks the calling agent's role before forwarding. The coder role can read files and run tests, but cannot push to GitHub. The boomerang-git role is the only one allowed to use the github-mcp server. The playwright server is restricted to tester, researcher, and scraper. This is enforced in code at access/access.go -- 23 roles, 7 restricted server classes.

The practical effect: agents never see tools they can't use, which cuts the tool list in their prompt and reduces token overhead by up to 95% per dispatch. The broker also routes the actual call, retries on failure, and logs every invocation to the audit log.

Container Support -- First-Class Deployment Option¶

Neuralgentics ships with four container images on pgvector/pgvector:pg18 multi-stage builds:

• ghcr.io/veedubin/neuralgentics-postgres:v0.9.4 — PostgreSQL 18 + pgvector, schema baked in
• ghcr.io/veedubin/neuralgentics-sidecar:v0.9.4 — Python gRPC embedding service
• ghcr.io/veedubin/neuralgentics-backend:v0.9.4 — Go JSON-RPC backend, distroless

Bring up the full stack with docker-compose up or podman-compose up. The podman-compose.yml includes Podman-specific tweaks (SELinux :Z labels, userns_mode: keep-id, pids_limit).

See Installation Guide for the container quickstart.

    ROLE x SERVER MATRIX
    ─────────────────────────────────────────────────────────────────
    SERVER          architect  coder  tester  git  writer  scraper
    ─────────────────────────────────────────────────────────────────
    filesystem          ✓        ✓      ✓      ✓     ✓       ✓
    postgres            ✓        ✓      ✓      ✓     ✓       ✓
    shell               ✓        ✓      ✓      ✓     ✓       ✓
    ─────────────────────────────────────────────────────────────────
    github-mcp          ✗        ✗      ✗      ✓     ✗       ✗
    playwright          ✗        ✗      ✓      ✗     ✗       ✓
    searxng             ✓        ✓      ✗      ✓     ✗       ✓
    markitdown          ✓        ✗      ✗      ✓     ✓       ✗
    webfetch/search     ✓        ✓      ✓      ✗     ✗       ✓
    ─────────────────────────────────────────────────────────────────
    23 total roles  ·  7 restricted servers  ·  default-deny

See Permission Model for the full matrix and Broker Flow for the request path.

Kanban Board -- A Real FSM, Not a TODO List¶

Tasks are first-class objects with a 7-state finite state machine: triage → todo → ready ↔ running ↔ blocked → done → archived. Every transition is a logged event. failureLimit=2 auto-archives a card that keeps failing. The kanban is the durable source of truth for "what is being worked on" -- agents and humans read the same board, and the orchestrator only dispatches cards in ready status.

The board survives session boundaries, so a card you start on Monday is still on the board Friday morning with its full dispatch history attached.

The kanban is now a markdown file (TASKS.md) in your project root, not a TUI screen. Here's an example of what it looks like:

# Kanban Board

## Triage
- [ ] T-070: Review PR #123 for security vulnerabilities

## Todo
- [ ] T-068: Fix broken doc links in `docs/index.md`

## Ready
*(Empty)*

## Running
- [x] T-069: Implement feature flags for dark mode (Assigned: @coder)

## Blocked
*(Empty)*

## Done
- [x] T-067c: Fix mutex deadlock in memory store (12s)
- [x] T-067b: Clean up unused imports in `store/queries.go` (8s)
- [x] T-067a: Add vnode type validation (14s)
- [x] T-065: Fix scan error propagation (21s)

## Archived
- [x] T-066: Implement count query (auto-archived: failure > 2)

See Kanban System for the FSM transitions, circuit-breaker rules, and dispatch logic.

Tiered Context Loading -- L0 / L1 / L2¶

Memory loads in three tiers by trust and recency. L0 is a ~100-token project summary built from high-trust memories, injected automatically at session start so a new agent can orient. L1 is a ~2K-token summary of key decisions (trust ≥ 0.8) used during planning. L2 is the full memory store, queried on demand when the agent needs a specific past decision.

The result: agents start with the same context humans do after skimming a project wiki. They don't have to read 50,000 tokens of history to know the architecture exists.

    CONTEXT TIERS  ·  loaded on demand
    ─────────────────────────────────────────────────────────────────
    L0  ~100 tokens   project summary
        ↳ "Neuralgentics: 23-role MCP broker + pgvector memory.
            Architect designs, coder implements, tester gates.
            Trust-scored, L0/L1/L2 loading. MIT license."
        always-injected at session start (trust ≥ 0.5)

    L1  ~2,000 tokens   key decisions
        ↳ routing matrix, RBAC table, FSM transitions,
          decay formula, release pipeline, zero-error rule
        loaded during planning (trust ≥ 0.8)

    L2  unbounded   full memory store
        ↳ every decision, every dispatch, every wrap-up
        queried semantically per task
    ─────────────────────────────────────────────────────────────────
    Prompt budget: 200 tokens for the agent + 100 L0 + 2K L1 on demand

See Memory System Reference for the tier promotion logic and trust thresholds.

Multi-Agent Routing -- 23 Specialists, One Routing Matrix¶

The orchestrator owns a single routing matrix that maps task type to specialist agent. "Design a new feature" goes to architect. "Implement this card" goes to coder. "Run the test suite" goes to tester. "Open a PR" goes to git. "Write the release notes" goes to writer. The matrix is enforced at the code level, not by convention -- an agent cannot accidentally call a tool its role doesn't authorize.

Eight concrete agent roles ship in the project: architect, coder, explorer, git, orchestrator, reviewer, tester, writer. The 23 in the broker matrix extend these with finer-grained permission scopes.

    ROUTING MATRIX  ·  intent → agent
    ─────────────────────────────────────────────────────────────────
    INTENT              PRIMARY AGENT     CONTEXT     GATES
    ─────────────────────────────────────────────────────────────────
    design / spec       architect         L0 + L1    --
    implement / fix     coder             L0         lint+tsc+test
    find / locate       explorer          L0         --
    commit / push       git               L1         diff+lint
    test / cover        tester            L0         test only
    review / audit      tester            L1         read-only
    document / write    writer            L0         markdownlint
    web / scrape        scraper           L0         --
    orchestrate         orchestrator      L0 + L1    all gates
    ─────────────────────────────────────────────────────────────────
    Unknown intent → orchestrator self-routes after L1 planning

See Dispatch Flow for the full routing logic and the rule that architect always designs before coder builds.

Stateless Agent Protocol -- 200-Token Prompts, Durable State¶

Agents don't receive large inline context packages. They receive a ~200-token seed prompt that says Task: <verb> the <noun>. Memory ID: <id>. Action: fetch context from memory and execute. The agent fetches its context from memory, does the work, stores its wrap-up back to memory, and returns a {memory_id, description} handle to the orchestrator.

This decoupling means agents can be swapped, scaled, or restarted without losing state. The memory is the source of truth, the prompt is just a delivery envelope. Token overhead per dispatch drops to a few hundred tokens, and a fresh agent picks up exactly where the last one left off.

    ─── ORCHESTRATOR ──→ MEMORY (store context) ──→ AGENT (seed prompt)
    Task: Fix the broken count query in store/queries.go.
    Memory ID: mem-7c3a-4f2e
    Action: Fetch context from memini-core, fix the bug, store wrap-up.

    ─── AGENT ──→ MEMORY (fetch context) ──→ [executes] ──→ wrap-up
    → Reads L0 summary, L1 routing rules, L2 prior count-query bug
    → Edits store/queries.go, simplifies COUNT(*), adds regression test
    → Stores wrap-up: "Fixed CountMemories. Replaces mem-9b1a."

    ─── AGENT ──→ ORCHESTRATOR (return handle)
    { memory_id: "mem-a8f3", description: "count query simplified" }

See Session Lifecycle for the full 8-step protocol and the wrap-up trust signal.

Why It's Different¶

• Memory is a product, not a side effect -- trust scoring and decay make the system honest about what worked. Source: packages/memini-core/
• Permissions are the broker, not a config file -- 23 roles x 7 restricted server classes, enforced in code. Source: access/access.go
• State lives in memory, not in prompts -- ~200-token seed prompts, full context fetched on demand, wrap-ups stored back. See Session Lifecycle
• A real kanban FSM, not a TODO list -- 7 states, circuit breaker, audit trail. See Kanban System

Comparison Table¶

Comparison data verified against public sources as of 2026-06. Cells marked (needs research) were not citable at time of writing.

See It In Action¶

A mockup is a picture of the app, drawn in plain text with Unicode box-drawing characters. Like the dispatch diagram above, but drawn to look like a screenshot of the running terminal UI -- header bar, agent names, footer hints. No PNG files required.

Example: Kanban Board (TASKS.md)¶

The kanban board is now a markdown file in your project root. Here's an example:

# Kanban Board

## Triage
- [ ] T-070: Review PR #123 for security vulnerabilities

## Todo
- [ ] T-068: Fix broken doc links in `docs/index.md`

## Ready
*(Empty)*

## Running
- [x] T-069: Implement feature flags for dark mode (Assigned: @coder)

## Blocked
*(Empty)*

## Done
- [x] T-067c: Fix mutex deadlock in memory store (12s)
- [x] T-067b: Clean up unused imports in `store/queries.go` (8s)
- [x] T-067a: Add vnode type validation (14s)
- [x] T-065: Fix scan error propagation (21s)

## Archived
- [x] T-066: Implement count query (auto-archived: failure > 2)

Example: Memory Inspector¶

The memory inspector is now a CLI tool that queries the PostgreSQL backend. Here's an example of its output:

$ neuralgentics memory query "dispatch routing matrix"

Query: "dispatch routing matrix"
Results: 3 (tiered search)

ID            Trust  Decay/Day  Used  Age     Content
────────────────────────────────────────────────────────────────────────────────
a1b2c3d4...  0.85   0.02       4     12d    "Routing Matrix: task type → architect for design, coder for implementation — enforced at code level, no exceptions"
e5f6g7h8...  0.78   0.05       3     3d     "Context Package: fetch L0/L1 memory, attach to Task() — L0 ~100 tokens, L1 ~2K tokens for planning"
i9j0k1l2...  0.62   0.08       2     1d     "404 fix: mkdocs.yml site_url wrong — correct URL is veedubin.github.io/neuralgentics"

Trust: ● active (>0.5)   ○ fading (<0.5)   ∅ archived (<0.2)

Quickstart¶

1. Bootstrap your project:

   npx @veedubin/neuralgentics --init
   

2. Launch OpenCode:

   cd your-project
   opencode
   

Quick Links¶

Get Started →

Built by humans who got tired of agents that forget.