Neural Context Protocol

Neural Context Protocol

[](https://github.com/kulkarni2u/neural-context-protocol/actions/workflows/ci.yml)

-----

A protocol for agent-to-agent communication over MCP

NCP is an agent-to-agent communication protocol for multi-agent systems — and, underneath it, a memory bus over MCP. It lets agents talk to each other, hand off work, and build on prior results without replaying transcripts or stuffing prompts.

MCP standardized how a single agent talks to its tools. NCP standardizes how agents talk to each other. It exposes one MCP endpoint that every host — Claude, Codex, OpenCode, n8n, LangGraph, or a custom orchestrator — connects to as a peer. Each agent reads bounded, trust-weighted context, writes durable memory, and sends bounded signals (whispers) to other agents, all through the same protocol.

The protocol rides on a memory bus: durable shared state, relevance-bounded retrieval, and trust scoring are what make the conversation between agents reliable. Making token spend compound is the payoff that follows.

| Problem | What the bus provides | |---------|-------------------| | Agents have no shared channel between turns | One MCP memory bus every host connects to | | Agents replay growing transcripts | Bounded context assembly per turn | | Useful work disappears after a turn | Durable memory and turn records | | Multi-agent handoff is brittle | Whispers and shared pipeline memory | | All context looks equally credible | Trust scores, drift markers, dissent, calibration | | Token spend does not compound | Reusable memory, cost telemetry, reputation signals | | Teams want to use smaller models safely | Better engineered context for cheaper model calls |

-----

Why a memory bus

In a multi-agent system, the hard problem is not any single model — it is the channel between agents. Without one, every agent is an island: it re-reads context, re-discovers prior decisions, and leaves no reusable signal behind. Handoffs degrade into pasting full transcripts forward.

NCP is that channel. It is a bus, not an orchestrator: agents attach to it as peers, publish memory and signals, and subscribe to bounded, relevance-ranked context. The orchestrator still decides who runs when; the bus owns what they know and share.

Three properties make it a bus and not just a store:

• Bounded reads. Every agent gets a budget-bounded working context, not the whole history — so the channel scales as turns and agents grow.
• Directed signals. Agents emit whispers to specific peers (handoffs, dissent, drift reports) without broadcasting full state.
• Trust-aware transport. Every message on the bus carries a trust score and drift marker — self-reported, advisory inputs, not runtime-verified truth — so a receiving agent knows how much to believe what it reads.

The payoff compounds at the organization level as token capital efficiency — the business value captured per dollar spent on model reasoning. Because work persists as reusable, trusted state instead of being thrown away at the end of each turn, token spend accrues into shared organizational memory rather than resetting: decisions, evidence, outcomes, trust signals, and cost records that future runs, teams, and pipelines draw on. Future agents — including cheaper or smaller models — stand on prior work without replaying the whole history. That does not make NCP a model router or eval platform; it is the context substrate those loops need. The [Benchmarks](#benchmarks) section quantifies the effect.

-----

Quickstart

pip install neural-context-protocol
ncp init
ncp serve --host 127.0.0.1 --port 4242 --cwd /path/to/project

For Claude Code:

cp examples/06_claude_code/mcp_servers.json .mcp.json

See [examples/06_claude_code/README.md](./examples/06claudecode/README.md).

For Codex CLI, copy [examples/07_codex_cli/mcp_servers.json](./examples/07codexcli/mcp_servers.json) into your Codex MCP config location.

See [examples/07_codex_cli/README.md](./examples/07codexcli/README.md).

For Codex CLI and OpenCode, register the same endpoint and copy the host's AGENTS.md turn contract — see [examples/07_codex_cli/README.md](./examples/07codexcli/README.md) and [examples/09_opencode/README.md](./examples/09_opencode/README.md).

For n8n, NCP's MCP server must be reachable from your n8n instance with an auth token configured — see [examples/08_n8n/README.md](./examples/08_n8n/README.md).

ncp init creates .ncp/config.toml and a CLAUDE.md turn contract in the project root. When run interactively, it also detects installed claude, codex, and opencode CLIs and asks whether to add the matching NCP hook/setup files.

Zero-touch setup (route all agent comms through NCP)

For Claude Code, Codex CLI, and OpenCode you can go further than registering the server: setup files can start/check the bus automatically and instruct every session — and any subagents it dispatches — to use NCP as the agent-to-agent channel.

mkdir -p .claude/hooks .claude/skills/ncp
cp examples/06_claude_code/settings.json             .claude/settings.json
cp examples/06_claude_code/hooks/ncp-session-start.sh .claude/hooks/
cp examples/06_claude_code/skills/ncp/SKILL.md        .claude/skills/ncp/
chmod +x .claude/hooks/ncp-session-start.sh

The setup files health-check 127.0.0.1:4242/healthz, start ncp serve if it's down, and inject the protocol instruction (including the mandatory subagent dispatch rule). Codex uses .codex/hooks.json; OpenCode uses a project plugin at .opencode/plugins/ncp.js. Hooks and contracts instruct hosts to use NCP — they don't enforce it; reliable coverage comes from registering the MCP tools, the always-loaded instructions, the dispatch template, and the session-start nudge together. See [examples/06_claude_code/README.md](./examples/06claudecode/README.md), [examples/07_codex_cli/README.md](./examples/07codexcli/README.md), and [examples/09_opencode/README.md](./examples/09_opencode/README.md).

-----

How agents talk over the bus

Instead of treating every model call as an isolated chat, NCP assembles a shared working context from three blocks every turn. Each block is a different channel on the bus:

[NCP:CONSCIOUS]     what this agent knows right now
[NCP:SUBCONSCIOUS]  relevant past, retrieved not replayed
[NCP:WHISPERS]      bounded signals from other agents

Memory survives restarts. The same runtime serves multiple hosts against the same store. Agents coordinate through bounded whispers without stuffing prompts.

Concrete example: a 3-agent bugfix on the bus

This is where the memory bus starts paying for itself.

Say you have a 30-module Java monorepo and a bug in PaymentProcessor.java. You run three agents on the same pipeline_id: analyzer, fixer, reviewer. They never see each other's transcripts — they communicate only through the bus.

analyzer reads the file, runs the affected tests, and publishes one distilled chunk instead of pasting a full stack trace into the next prompt:

NPE at PaymentProcessor.java:142.
root_cause: retryCount is null when payment_method=ACH and customer.tier=trial.
Guard missing before .intValue() call.

fixer does not receive the full transcript. It reads bounded context from the bus, retrieves that chunk by relevance, opens PaymentProcessor.java fresh with its own tools, applies the null guard, runs the targeted tests, and publishes the outcome:

Null guard applied at PaymentProcessor.java:142.
if (retryCount == null) retryCount = 0.
PaymentProcessorTest.testAchTrialRetry passes.

reviewer reads its own bounded context, sees the fix outcome, and receives a bounded whisper with the changed file list. If the fix is wrong, it emits a dissent whisper directed back to fixer with the specific issue — a targeted message on the bus, not a full-history replay.

By turn 20, a raw-replay workflow is dragging old stack traces, earlier tool output, and prior reasoning through every turn. The bus workflow is working from durable shared memory, current task context, and trust-weighted evidence.

Turn flow

flowchart TD
    A["Host calls ncp_get_context"]
    B["Assembler loads conscious state"]
    C["Resolve recent refs"]
    D["Retrieve top relevant chunks"]
    E["Drain bounded whispers"]
    F["Assemble bounded context"]
    G["Host runs provider turn"]
    H["Host persists durable memory"]

    A --> B --> C --> D --> E --> F --> G --> H

Architecture

flowchart LR
    A["Claude / Codex / OpenCode / n8n / other MCP hosts"]
    B["ncp serveHTTP/SSE MCP runtime"]
    C["Assemblerbounded context + retrieval"]
    D["SQLite modelocal-first store"]
    E["pgvector modedurable memory"]
    F["Rediswhispers + fetch-session state"]

    A --> B
    B --> C
    C --> D
    C --> E
    C --> F

Every connected agent is a peer on the bus (A); ncp serve is the transport; the assembler and stores are the bus internals.

-----

Memory layers

Memory on the bus is not a flat blob. Every chunk carries a required layer tag, drawn from a fixed set of five cognitively-named values, so you can filter retrieval by what kind of memory you want (ncp_fetch takes a layer filter, and ncp status / ncp viz report the distribution).

The valid layers are episodic, procedural, semantic, social, and reasoning_trace. Four of them are a writer-chosen convention — NCP stores and filters by the tag but does not enforce a meaning, so use them consistently with their usual sense:

| Layer | Conventional use | |-------------------|-----------------------------------------------------------------| | episodic | What happened — events, observations, tool results from a turn | | procedural | How to do something — repeatable steps and methods | | semantic | Stable facts and definitions that outlive a single run | | social | Agent-to-agent context — who said what, handoffs, dissent |

reasoning_trace is the exception: it is set automatically — ncp_record_decision writes the decision rationale as a reasoning_trace chunk. Tagging memory consistently is what lets the bus retrieve "the decision rationale" or "the procedure" rather than just "a recent chunk."

-----

Trust-aware transport

Most frameworks treat stored context as equally credible. The bus doesn't. Trust is part of the protocol, so a receiving agent always knows how much to believe a message.

Every memory chunk carries a base_trust score (derived from its src at write time) and a written_at_drift marker. Both base_trust and drift_score are self-reported, client-asserted advisory inputs — NCP does not yet compute drift itself. Retrieval scoring discounts chunks written during high-drift periods, and the CoherenceChecker reads the per-turn drift_score agents report and fires alerts when it crosses threshold. Agents emit world_check whispers to report drift back onto the bus. A runtime-computed drift signal is future work — see the [north-star roadmap](./docs/NCPNORTHSTARCAPABILITYROADMAP.md) (WI-016).

ChunkSource:      user_verified | tool_result | agent_inferred | synthesis
base_trust:       float (0.0–1.0) — advisory weight applied at retrieval time
drift_score:      float (0.0–1.0) — self-reported coherence signal (advisory; not runtime-computed)
written_at_drift: float — drift level reported when this memory was written

The effect: each agent receives context ranked by how much it should believe it, not just by recency.

Per-chunk trust is only half the story. Trust on the bus also attaches to who wrote it — see agent identity and reputation below.

-----

Agent identity and reputation

In a multi-agent system, "how much do I trust this message" depends on who sent it. NCP gives agents real, cryptographic identities, lets them optionally sign what they write, and tracks a reputation for each one. Reputation is computed and displayed by default; it can also weight retrieval and gate whispers, but only when an operator opts in (CAP-T4 — see below).

Cryptographic identity. ncp identity create generates an Ed25519 keypair; the identity ID is derived from the SHA-256 of the public key, and the secret key is written to a 0700 keystore (~/.ncp/keys, or NCP_KEYSTORE_DIR). Public keys are registered in the store; keys can be listed and revoked.

ncp identity create --label fixer   # prints the new identity_id
ncp identity list
ncp identity revoke 

Optional authorship signing. ncp_write_memory and ncp_emit_whisper accept an optional signature over a canonical written_by | sha256(content) | pipeline_id payload; NCP verifies it against the author's registered public key, persists the result, and surfaces a verified marker in fetch results and the pidgin wire format. This is opt-in and off by default: it is gated behind [identity].require_signatures, which defaults to false, so unsigned writes still work and authorship is not authenticated unless an operator turns enforcement on. With require_signatures = true, writes that cannot be verified — including those from revoked identities — are rejected.

Reputation as a Beta posterior. Each identity carries a Beta distribution (alpha, beta) over "produces trustworthy memory." When ncp calibrate --feedback runs, the per-chunk trust changes it computes are rolled up to the chunk's author: trust gains become positive evidence, dissent-driven losses become negative evidence. A forget factor decays old evidence so reputation tracks recent behavior, and gain scales how fast evidence accrues. The reported score is the posterior mean; confidence rises with the number of observations.

ncp reputation             # score, confidence, and observation count per identity

Tune it under [reputation] in .ncp/config.toml (gain, forget, confidence_k) or via NCP_REPUTATION_*. An agent that has repeatedly produced disputed memory earns a lower reputation. Since Sprint 4 that score can also act on the bus — each piece is opt-in and off by default:

• Outcomes as evidence (CAP-T3) — ncp_record_outcome records task success/failure against the chunks (or turn) that informed it; ncp calibrate --feedback consumes each outcome exactly once as the primary trust/reputation signal, ahead of the retrieval-count prior ([retrieval].usage_prior_weight).
• Reputation-weighted retrieval (CAP-T4) — [retrieval].reputation_weight (default 0.0) blends the author's reputation confidence into chunk trust at ranking time, identically across the SQLite, pgvector, and async pgvector backends.
• Whisper gating (CAP-T4) — [whispers].min_author_reputation (default 0.0) drops whispers from low-reputation authors at drain time. It gates on the claimed sender: sender identity is only as strong as [identity].require_signatures enforcement, which also stays off by default.
• Work memoization (CAP-C3) — [memoization].enabled (default false) turns on ncp_lookup_memo/ncp_record_memo, a signature-keyed memo of completed work. It is lookup-only: NCP surfaces memo hits, misses, and an estimated tokens-saved figure in ncp status, and the host decides whether a memo lets it skip its own model call.

-----

Retrieval and self-improving memory

Retrieval on the bus is hybrid multi-signal fusion, not pure recency or pure vector search. RetrievalPolicy (ncp/stores/retrieval.py) blends three signals with weights that must sum to 1.0:

score = w_lexical · BM25 + w_recency · recency + w_trust · base_trust
        (defaults 0.5 / 0.3 / 0.2; recency half-life 4h)

Two multiplicative penalties then shape the result:

• Drift discount — ch

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kulkarni2u
• Source: kulkarni2u/neural-context-protocol
• License: MIT
• Homepage: https://pypi.org/project/neural-context-protocol/

Install and usage instructions live in the source repository linked above.