Metadata-Version: 2.4
Name: neural-context-protocol
Version: 0.1.0a1
Summary: Neural Context Protocol (NCP): bounded, persistent context for multi-agent pipelines.
Author: kulkarni2u
License-Expression: MIT
Project-URL: Homepage, https://github.com/kulkarni2u/neural-context-protocol
Project-URL: Repository, https://github.com/kulkarni2u/neural-context-protocol
Project-URL: Issues, https://github.com/kulkarni2u/neural-context-protocol/issues
Keywords: mcp,agents,multi-agent,context,memory,sqlite,llm,protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.7
Requires-Dist: rank-bm25>=0.2.2
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.0
Requires-Dist: httpx>=0.27
Requires-Dist: anyio>=4.3
Requires-Dist: orjson>=3.10
Requires-Dist: structlog>=24.0
Provides-Extra: providers
Requires-Dist: anthropic; extra == "providers"
Requires-Dist: openai; extra == "providers"
Requires-Dist: google-generativeai; extra == "providers"
Requires-Dist: mistralai; extra == "providers"
Requires-Dist: cohere; extra == "providers"
Provides-Extra: http
Requires-Dist: aiohttp; extra == "http"
Provides-Extra: redis
Requires-Dist: redis; extra == "redis"
Provides-Extra: pgvector
Requires-Dist: psycopg2-binary; extra == "pgvector"
Requires-Dist: pgvector; extra == "pgvector"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: pytest-httpx; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"

# Neural Context Protocol

[![CI](https://github.com/kulkarni2u/neural-context-protocol/actions/workflows/ci.yml/badge.svg)](https://github.com/kulkarni2u/neural-context-protocol/actions/workflows/ci.yml)
![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)

Neural Context Protocol (NCP) is a local-first context runtime for multi-agent
systems. It keeps context bounded, persists useful memory across turns and
restarts, and exposes that shared context over MCP so multiple tools can work
from the same state instead of replaying full history.

In the included benchmarks, NCP reduced peak prompt size by `17.52x` on a
coding pipeline and `16.35x` on a research pipeline versus naive history replay.

## Why NCP

Multi-agent workflows usually break down in three predictable ways:

- prompt history keeps growing until token cost and latency get ugly
- agents lose useful state between turns or after a restart
- each tool has its own silo, so context does not move cleanly across workers

NCP addresses that with:

- bounded context assembly for the current turn
- durable shared memory in a project-local SQLite store
- targeted mid-turn retrieval with `ncp_fetch`
- cross-agent signaling with whispers
- one MCP surface that multiple coding tools can share

## What Is Proven Today

This repo is in an early alpha V1 state with a SQLite-first runtime and
HTTP/SSE MCP as the public transport.

What is already proven in this repository:

- Claude and OpenCode both connect to the same NCP MCP server over HTTP
- both hosts can write shared memory through MCP
- both hosts can retrieve memory written by the other host
- both hosts can deliver and receive whispers through the shared MCP runtime
- restart persistence is validated by the dogfood harness
- bounded-context benchmarks are reproducible and show large prompt reduction

Current benchmark snapshot:

- coding pipeline: peak `174` NCP tokens vs `1927` naive replay, `17.52x` reduction
- research pipeline: peak `156` NCP tokens vs `1700` naive replay, `16.35x` reduction

## Quick Start

```bash
pip install -e .
ncp init
ncp serve --host 127.0.0.1 --port 4242 --cwd /path/to/project
ncp status --cwd /path/to/project
```

Expected success signals:

- `ncp init` creates `.ncp/config.toml` and `CLAUDE.md`
- `ncp serve` starts the local HTTP MCP server on `127.0.0.1:4242`
- `ncp status` prints store metrics such as chunk count and whisper count

Published alpha install path:

```bash
pip install neural-context-protocol
```

For a deeper setup path, see [docs/NCP_SETUP.md](./docs/NCP_SETUP.md).

## How It Works

NCP keeps one shared SQLite store per project and serves it over MCP:

```text
Claude Code  ─┐
Codex        ─┼→  ncp serve (HTTP/SSE MCP)  →  .ncp/store.db
OpenCode     ─┘
```

Each agent turn works roughly like this:

1. call `ncp_get_context`
2. get a bounded, assembled context block for the current role and task
3. optionally call `ncp_fetch` for targeted retrieval mid-turn
4. persist useful results with `ncp_write_memory`
5. send light-weight cross-agent signals with `ncp_emit_whisper`

Example assembled context:

```text
[NCP:CONSCIOUS]
agent:planner role:plan task:verify_shared_memory slot:bounded_context

[NCP:SUBCON]
chunk:sub_2267717ed22a layer:semantic
  opencode_http_probe_20260524T230734Z

[NCP:WHISPERS]
wsp from:opencode to:claude t:nudge c:0.96 age:1s
  whisper_probe_opencode_to_claude_20260524T232132Z
```

## MCP Transport

NCP’s public transport is HTTP/SSE MCP:

```bash
ncp serve --host 127.0.0.1 --port 4242 --cwd /path/to/project
```

Endpoints:

- `GET /healthz`
- `GET /sse`
- `POST /mcp`

Use this endpoint in MCP host configs:

- `http://127.0.0.1:4242/mcp`

The public HTTP path is validated end to end by the dogfood harness, not just
by unit tests.

## Benchmarks

Runnable benchmark commands:

```bash
python3 benchmarks/coding_pipeline/run.py --turns 40
python3 benchmarks/research_pipeline/run.py --turns 36
```

Benchmark write-ups:

- [docs/NCP_BENCHMARK_CODING_PIPELINE.md](./docs/NCP_BENCHMARK_CODING_PIPELINE.md)
- [docs/NCP_BENCHMARK_RESEARCH_PIPELINE.md](./docs/NCP_BENCHMARK_RESEARCH_PIPELINE.md)

## Examples

Runnable examples:

```bash
python3 examples/01_quickstart.py
python3 examples/02_multi_agent.py
```

Integration examples:

- `examples/06_claude_code/` - Claude Code setup and MCP config
- `examples/07_codex_cli/` - Codex CLI MCP config and session loop

## Current Scope

This repository currently ships:

- core NCP types and encoder
- chunking and bounded assembly
- SQLite-backed persistence
- HTTP/SSE MCP server
- dogfood validation harness
- local adapter plus provider adapter surface
- release preflight script
- minimal CI for `ruff`, `pytest`, and `build`

Next release step:

- publish the first alpha release

## Documentation

- [docs/NCP_SETUP.md](./docs/NCP_SETUP.md) - install and first-run setup
- [docs/NCP_PROTOCOL_SPEC.md](./docs/NCP_PROTOCOL_SPEC.md) - normative protocol reference
- [docs/NCP_MCP_DOGFOOD_LOOP.md](./docs/NCP_MCP_DOGFOOD_LOOP.md) - deterministic MCP proof path
- [docs/NCP_PROVIDER_PARITY_BASELINE.md](./docs/NCP_PROVIDER_PARITY_BASELINE.md) - current live host parity snapshot
- [CHANGELOG.md](./CHANGELOG.md) - release-facing change summary

## Release Preflight

```bash
bash scripts/release_preflight.sh
```

<details>
<summary>Provider notes</summary>

- `GeminiAdapter` currently uses `google.generativeai`, which is deprecated upstream. The adapter is functionally green in tests, but should migrate to `google.genai` in a future pass.
- `CohereAdapter` is functionally green, but the current upstream SDK emits Python deprecation warnings during tests.

</details>
