Temporal Knowledge Substrate

An MCP server that lets LLM agents accumulate organizational knowledge across sessions, scoped by domain, backed by Neo4j. Tools enforce structural invariants so the graph can't corrupt itself — no raw Cypher writes.

Two-layer architecture:

• Process layer — Domains own Sessions. Sessions chain forward in time via NEXT_SESSION. The arrow of time is enforced by the tool, not by instructions.
• Knowledge layer (append-only) — 10 ontological types + 5 sub-labels via Neo4j multi-labeling, connected by 11 relationship types. Knowledge evolves via EVOLVED_FROM chains — every prior moment is preserved, never overwritten.

The principle: the tool may make claims about the graph but may not make claims about consciousness. Collisions error rather than silently merge. Description changes always create a new chain node — update_knowledge and retype_knowledge do not exist by design. See HOWTO.xml for the operator-facing teaching, and docs/design/ for the design archive.

Prerequisites

• Python 3.10+
• uv package manager
• Neo4j 5.x instance (local or remote)

Quick Start

# Install
uv sync

# Run (stdio transport, default for MCP clients)
mcp-temporal-knowledge --db-url bolt://localhost:7687

Configuration

All options can be set via CLI flags or environment variables. CLI takes precedence.

MCP Client Configuration

Claude Desktop / Claude Code

Add to your MCP config:

{
  "mcpServers": {
    "temporal-knowledge": {
      "command": "mcp-temporal-knowledge",
      "args": ["--db-url", "bolt://localhost:7687"]
    }
  }
}

HTTP transport

mcp-temporal-knowledge \
  --db-url bolt://localhost:7687 \
  --transport streamable-http \
  --server-host 0.0.0.0 \
  --server-port 8000 \
  --allow-origins "http://localhost:3000" \
  --allowed-hosts "localhost,127.0.0.1"

Tool Surface (22 tools)

Session workflow

Every session follows: create_domain (once) → begin_session → create/evolve/confirm knowledge → end_session

Knowledge mutation

Querying

Taxonomy & Analytics

Type System

Every knowledge node carries:

• Exactly one ontological label (one of 10 below)
• An ont_type property naming that label deterministically
• Zero or more sub-labels via Neo4j multi-labeling

API ergonomics: create_knowledge accepts either an ontological type (Actor) or a known sub-label (Person) as the type field. When a sub-label is given, the substrate auto-applies BOTH labels via multi-labeling (e.g., (:Actor:Person)).

Upgrading from v0.6.x

v0.7.0 is a breaking change. Migration script:

.venv/bin/python -m mcp_temporal_knowledge._migration.v0_7_0 \
    --db-url bolt://localhost:7687 \
    --username neo4j --password ... \
    --database <name> \
    [--dry-run]

Eight phases, each independently reversible. --database is required (Neo4j Desktop 2 hosts multiple named databases on one instance). Phase 7 (Dependency reclassification) is operator-assisted — the script lists nodes for manual reclassification. See CHANGELOG.md for the full breaking-change inventory and docs/design/ for the principle and design archive.

Development

# Install with dev dependencies
uv sync --dev

# Run tests
uv run pytest

# Type checking
uv run pyright

See HOWTO.xml for the ontological commitments and tool behavior. Provide this to the LLM as invariant scaffolding.