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 (immutable) — Domains own Runs, Runs chain forward in time via NEXT_RUN. The arrow of time is enforced by the tool, not by instructions.
• Knowledge layer (append-only) — 10 entity types (System, Process, Configuration, Gotcha, Rationale, etc.) connected by 7 relationship types. Knowledge evolves via EVOLVED_FROM chains — old versions are preserved, never overwritten.

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.

CLI Flag	Env Var	Default	Description
--db-url	NEO4J_URI or NEO4J_URL	bolt://localhost:7687	Neo4j connection URL
--username	NEO4J_USERNAME	neo4j	Neo4j username
--password	NEO4J_PASSWORD	password	Neo4j password
--database	NEO4J_DATABASE	neo4j	Neo4j database name
--transport	NEO4J_TRANSPORT	stdio	Transport: stdio, sse, or streamable-http
--namespace	NEO4J_NAMESPACE	(none)	Tool name prefix (e.g. myapp -> myapp-begin_session)
--server-host	NEO4J_MCP_SERVER_HOST	127.0.0.1	HTTP host (non-stdio transports)
--server-port	NEO4J_MCP_SERVER_PORT	8000	HTTP port (non-stdio transports)
--server-path	NEO4J_MCP_SERVER_PATH	/mcp/	HTTP path (non-stdio transports)

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 (20 tools)

Session workflow

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

Tool	Description
list_domains	List all domains with run counts and last activity
create_domain	Create a knowledge domain (idempotent)
begin_session	Start a session — returns run_id needed by all knowledge tools
end_session	Close a session with a summary of what was learned

Knowledge mutation

Tool	Description
create_knowledge	Create entities (System, Gotcha, Rationale, etc.) linked to the current session
evolve_knowledge	Create a new version of an entity — old version preserved via EVOLVED_FROM
confirm_knowledge	Record that entities were reviewed and found unchanged
create_connections	Link entities (ENABLING, REQUIRING, CAUSING, etc.)

Querying

Tool	Description
search_knowledge	Fulltext search across names and descriptions
get_domain_state	All current (head-of-chain) entities for a domain
get_run_history	Session history — who worked on what, when
read_cypher	Read-only Cypher escape hatch (writes rejected)

Taxonomy & Analytics

Tool	Description
list_knowledge_types	The 10 entity types with descriptions
list_connection_types	The 7 knowledge + 4 process edge types
gds_create_projection	Create a GDS graph projection for analytics
gds_drop_projection	Drop a GDS projection
gds_pagerank	PageRank centrality
gds_betweenness	Betweenness centrality (bridge nodes)
gds_louvain	Louvain community detection
gds_wcc	Weakly connected components

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 the tools' behavior. Provide this to the LLM as invariant scaffolding.