Cognitive Substrate

mcp-cognitive-substrate

mcp-name: io.github.JaysonAIOnline/cognitive-substrate

A 28-layer cognitive substrate with cross-session Tree-of-Thoughts (ToT) evolutionary memory, conditional self-telemetry, and A2A tools for MCP agents.

Lets agents reason through a validated 28-layer substrate, evolve memory across sessions, and communicate with peer agents — all in one pip-installable package.

Features

• 28-layer cognitive substrate with Pydantic validation — CognitiveSubstrate validates reasoning through 6 families / 28 layers.
• Cross-session ToT evolutionary memory — SQLite-backed tree-of-thoughts nodes + substrate history; pruned branches become lessons for future sessions.
• Robust stack-based JSON parser — no regex; handles nested brackets, escaped strings, embedded code fences (robust_slice / robust_json_slice).
• Self-telemetry tool — get_cognitive_tree_state returns active paths and pruned branches for a session.
• Post-execution storage loop — store_5key_telemetry auto-saves compact 5-key telemetry (foundations, metacognition, defensive, resource, utility).
• 7 reasoning paradigms — deductive, inductive, abductive, analogical, causal, syllogistic, falsification.
• A2A tools — list, discover, call, and orchestrate peer agents.
• MCP server — exposes everything as tools via the cognitive-substrate CLI.

Install

pip install mcp-cognitive-substrate

Or install from source:

git clone https://github.com/JaysonAIOnline/mcp-cognitive-substrate.git

cd mcp-cognitive-substrate pip install -e .[test]

Requires Python >= 3.11.

Quick Start

from mcp_cognitive_substrate.substrate import CognitiveSubstrate

from mcp_cognitive_substrate.memory import get_cognitive_tree_state, store_5key_telemetry

substrate = CognitiveSubstrate() response = substrate.run("Your user prompt here") print(response["layers_applied"], "layers applied") print(response["substrate_verdict"])

Usage

28-layer substrate

from mcp_cognitive_substrate import substrate

Layer count and schema

print(substrate.layer_count()) # 28 print(substrate.SUBSTRATE_SCHEMA) # the full 6-family schema

Validate a prompt through the substrate

result = substrate.CognitiveSubstrate(session_id="s1").run("deploy safely") print(result["substrate_verdict"]) # heuristic pruning verdict

Run a single paradigm

from mcp_cognitive_substrate import run_paradigm print(run_paradigm("14_idempotency_side_effect_audit", {"evaluate_branch": True}))

Cross-session ToT evolutionary memory

from mcp_cognitive_substrate.memory import (

store_5key_telemetry, get_cognitive_tree_state, prune_failed_approach, )

node_id = store_5key_telemetry( session_id="session-a", payload={ "foundations": {"premise_validation": "assuming deps", "state_hash": "h", "falsification_notes": "deps missing"}, "defensive": {"blast_radius": "unpredictable", "is_idempotent": True, "invariant_rule": "r"}, "resource": {"big_o": "o(n)", "latency_bottleneck": "none"}, "utility": {"load_summary": "pin versions to deploy", "checklist_verified": True}, "metacognition": {"self_critique": "c", "drift_pct": 0.1}, }, score_delta=-110.0, ) prune_failed_approach(node_id) state = get_cognitive_tree_state("session-a", include_pruned=True) print(state["active_path_count"], state["pruned_branch_count"])

Stack-based JSON parser

from mcp_cognitive_substrate.memory import robust_slice, robust_json_slice

cleaned, payload = robust_slice('prefix {"a": {"b": [1, 2]}, "c": "x"} suffix')

payload == {"a": {"b": [1, 2]}, "c": "x"}; cleaned == "prefix suffix"

7 reasoning paradigms + A2A

from mcp_cognitive_substrate import reason, a2a_list, a2a_call, a2a_orchestrate

print(reason("Solve X", reasoning_type="abductive", depth=3)["steps"]) print(a2a_list()) print(a2a_call("peer-agent", "hello")) print(a2a_orchestrate("hi", capability="memory"))

As an MCP server

cognitive-substrate          # starts stdio MCP server

cognitive-substrate --info # prints package summary

All of the above — substrate paradigms, extraction/evaluation, memory store/recall, ToT lessons, tree-state telemetry, JSON parsing, reasoning plans, and A2A — are exposed as MCP tools.

Testing

pip install -e .[test]

python -m pytest src/tests -q # 16 tests

License

MIT