Kenning Reach

A category-1 conscious experience substrate: one person's envision–measure–actualize process, and the experience that gives it meaning, as an MCP server over Neo4j.

Kenning Reach is the a priori work behind Kenning Encounter. It holds a human frame's time as a continuous stream — a Genesis per day, TemporalFrames per session — and its possibility space as Envisionings that are opened, walked toward, and resolved by exactly one of released, evolved or actualized. The question it surfaced, "if time is a continuous stream for a category-1 entity, what is time for a category-3 one?", is the question the Encounter answers.

The ontology is formal

docs/design/ontology/v3.0.0.tql declares the graph's shape in TypeQL. gate.py proves it two-sided on synthetic data; audit_live.py imports a live graph into it and counts refusals; a unit test fails if the code's type sets drift from the model; an integration test exercises every rule on a real Neo4j. The rulings that shaped it, in the frame-holder's own words, are in docs/design/ontology/README.md.

Related MCP server: Graphiti-Memory MCP Server

Two layers

Process (constitutive): Genesis, Envisioning, TemporalFrame, and seven edges — OPENING, SEQUENCE, NAVIGATES_TOWARD, MEASUREMENT, ACTUALIZED, NEXT_GENESIS, DESCENDENT_FROM. Written only by process tools.

Experience (descriptive): eighteen node types and twelve edge types. Written by create_entities / create_relations, under the endpoint rules the model declares: nothing touches a Genesis; an Envisioning is always a referent and never a source; a TemporalFrame is the source of DISCOVERY only, and only INFORMING, RECOGNITION, VALIDATION and EXTENDING may point into it; every experience kind may point into an Envisioning.

Every node carries one label and t_created. There is no superlabel, no type property, no phase property: topology is the meaning.

Tools (22)

The full LLM-visible surface is in TOOL_DESCRIPTIONS.md (generated by scripts/gen_tool_descriptions.py). There is no write-Cypher tool by design.

Installation

Kenning Reach is not published to an index. Install from a checkout:

git clone https://github.com/kenningai/kenning-reach.git kenning-reach
cd kenning-reach
uv sync
uv run kenning-reach --help

Or as a container:

docker build -t kenning-reach:1.0.0 .

Requires Neo4j 5.x with APOC (core) and, for the GDS tools, the Graph Data Science library.

Configuration

Claude Desktop and the phone — Claude Code with Remote Control

deploy/ is also a Claude Code project: its .mcp.json names the local Reach over HTTP and its CLAUDE.md carries the operator discipline (navigate first, read back before writing, never infer, every frame about something held). Open the folder in Claude Desktop's Code tab, approve the server once, enable Remote Control by default, and the same session is reachable from the Claude iPhone or Android app while the computer is on. Execution and the graph stay on the machine; the phone is a window. deploy/compose.yml runs Neo4j (APOC, GDS) and Reach on the person's own machine, and deploy/GETTING_STARTED.md walks through the whole setup for someone who does not do this kind of work.

Custom connectors in Claude's settings are reached from Anthropic's servers, so a localhost address is refused by design. A session on the same machine, as above, is the way in.

Claude Code, or a hand-edited Claude Desktop config

"mcpServers": {
  "experience": {
    "command": "uv",
    "args": ["--directory", "/path/to/kenning-reach", "run", "kenning-reach"],
    "env": {
      "NEO4J_URL": "bolt://localhost:7687",
      "NEO4J_USERNAME": "neo4j",
      "NEO4J_PASSWORD": "<your-password>"
    }
  }
}

Environment Variables

CLI Flags

Every environment variable except NEO4J_MCP_STATELESS_HTTP has a corresponding CLI flag:

kenning-reach \
  --db-url "neo4j+s://..." \
  --username neo4j \
  --password secret \
  --database neo4j \
  --transport streamable-http \
  --server-host 0.0.0.0 \
  --server-port 8000 \
  --server-path /mcp/ \
  --namespace myapp \
  --read-timeout 60 \
  --schema-sample-size 500 \
  --allow-origins "https://example.com" \
  --allowed-hosts "example.com,www.example.com"

Transport Modes

• STDIO (default): Standard input/output for Claude Desktop and local tools

• Streamable HTTP (streamable-http): for web deployments and microservices

• SSE: Server-Sent Events for legacy web clients

Security

DNS Rebinding Protection

TrustedHost middleware validates Host headers. Only localhost and 127.0.0.1 allowed by default.

CORS Protection

No origins allowed by default (secure). Configure explicitly for web deployments:

kenning-reach --transport streamable-http \
  --allowed-hosts "example.com" \
  --allow-origins "https://example.com"

Docker

On your own machine — deploy/compose.yml

deploy/compose.yml is the supported deployment: Neo4j 5 with APOC and Graph Data Science, and Reach built from this checkout, on one computer. The graph lives in the reach-data volume on that machine and nowhere else.

cd deploy
cp .env.example .env        # then set REACH_PASSWORD
docker compose up -d

Neo4j Browser is at http://localhost:7474 and Reach at http://localhost:8000/mcp/, which is the address deploy/.mcp.json already uses. Set REACH_PORT, REACH_NEO4J_HTTP_PORT or REACH_NEO4J_BOLT_PORT in .env if a default port is taken. deploy/GETTING_STARTED.md walks through the same steps for someone who has not used Docker before.

Against an existing Neo4j

To run Reach alone against a Neo4j you already operate (with APOC, and GDS for the gds_* tools), build the image from a checkout at a sealed tag and give it the connection:

services:
  reach:
    build:
      context: /path/to/kenning-reach   # checkout at the tag
    image: kenning-reach:1.0.0
    ports:
      - "8000:8000"
    environment:
      NEO4J_URL: "neo4j+s://<your-instance>"
      NEO4J_USERNAME: "neo4j"
      NEO4J_PASSWORD: "${NEO4J_PASSWORD}"
      NEO4J_DATABASE: "neo4j"
      NEO4J_TRANSPORT: "streamable-http"
      NEO4J_MCP_SERVER_HOST: "0.0.0.0"
      NEO4J_MCP_SERVER_PORT: "8000"
      NEO4J_MCP_SERVER_PATH: "/mcp/"
      NEO4J_MCP_SERVER_ALLOWED_HOSTS: "reach.example.com"
    restart: unless-stopped

Name the hostnames clients will use in NEO4J_MCP_SERVER_ALLOWED_HOSTS rather than *; it is the DNS-rebinding guard. Custody still applies: the license's one use is a person's own experience, in their own custody.

Development

uv sync
uv run python -m pytest tests/unit -q
uv run python -m pytest tests/integration -q   # needs Docker
uv build

Mocked unit tests do not parse Cypher. After editing a .cypher file, run the integration test or EXPLAIN the file against a real Neo4j.

License

Hippocratic License 3.0 with the Mass Surveillance, Military Activities and Law Enforcement modules. See LICENSE. This is an ethical-source license, not an OSI-approved open-source license: the software is source-available, and it may not be used to model a person without their express written consent, nor by the actor classes the modules name.