+-----------------------------------------------------------------------------------+
|                AI Coding Agents (Claude Code / Cursor / Windsurf / AGY)           |
+-----------------------------------------+-----------------------------------------+
                                          |
                        JSON-RPC 2.0 over stdio / in-memory
                    (initialize, tools/call, resources/read, prompts/get)
                                          |
                                          v
+-----------------------------------------------------------------------------------+
|                           CortexMCPServer (server.py)                             |
|  Tools:                                                                           |
|   - memory_record_episode     - memory_query_entity                               |
|   - memory_upsert_fact        - memory_time_travel                                |
|   - memory_compile_context    - memory_verify_integrity                           |
+-------------------+-------------------------------------------+-------------------+
                    |                                           |
                    v                                           v
+---------------------------------------+   +---------------------------------------+
|   BiTemporalMemoryGraph (graph.py)    |   |      ContextCompiler (compiler.py)    |
|                                       |   |                                       |
| * Entities (service, module, ...)     |   | * Code-Aware Tokenizer (snake/Camel)  |
| * TemporalFacts (valid_from/until,    |   | * Okapi BM25 Lexical Scoring          |
|   singular conflict supersession)     |   | * 2-Hop Graph Spreading Activation    |
| * Episodes (ADR, bug_root_cause,      |   | * Stale-Fact Filter (valid_until=None)|
|   invariant, migration, incident)     |   | * Greedy Utility-Density Knapsack     |
| * Point-in-Time Snapshot & K-Hop BFS  |   |   Packing under strict `max_tokens`   |
| * SHA-256 Hashes + Graph Merkle Root  |   | * Provenance Citations (@sha256:...)  |
+-------------------+-------------------+   +---------------------------------------+
                    |
                    v
+---------------------------------------+
| Atomic JSON Snapshot Persistence      |
| (~/.cortex-mcp/memory.json)           |
+---------------------------------------+

pip install "git+https://github.com/codesphere-u/cortex-mcp.git@v1.1.0"
# After the first PyPI release: pip install cortex-bitemporal-mcp  (installs the `cortex-mcp` CLI; import name: cortex_mcp)
cortex-mcp --help

git clone https://github.com/codesphere-u/cortex-mcp.git
cd cortex-mcp
pip install -e ".[dev]"

python -m cortex_mcp.cli demo

==============================================================================
 CORTEX-MCP: BI-TEMPORAL KNOWLEDGE GRAPH & CONTEXT COMPILER DEMO
==============================================================================
Entities tracked      : 3
Active temporal facts : 6
Superseded stale facts: 2 (automatically retired)
Engineering episodes  : 4
SHA-256 Merkle Digest : e893bf67424f995283813e265a227224...
------------------------------------------------------------------------------
[Time-Travel Inspection @ 2026-02-01T00:00:00Z (Pre-PASETO Migration)]
  * auth_service --(uses_token_format)--> JWT_HS256
  * auth_service --(signing_primitive)--> HMAC_SHA256_SHARED_SECRET
------------------------------------------------------------------------------
[Compiled Active Context | Budget: 307/320 tokens (95.9%) | Suppressed Stale Facts: 2]
## Cortex-MCP Compiled Context (query: `auth_service token format signing_primitive and payment_ledger idempotency invariant`)
- [FACT:fact_auth_key_v2] `auth_service` --(signing_primitive)--> `Ed25519_Asymmetric_Keypair` (valid_from=2026-04-20T16:45:00+00:00, src=ep_adr_019)
- [FACT:fact_ledger_auth_dep] `payment_ledger` --(verifies_caller_via)--> `auth_service` (valid_from=2026-03-01T11:15:00+00:00, src=ep_inv_007)
- [INVARIANT:ep_inv_007] **INV-007: Payment Ledger Idempotency & Zero-Sum Double Entry** | files: src/payments/ledger.py
  Every mutation in payment_ledger MUST supply a deterministic idempotency_key and balance debit/credit postings to zero in a single SERIALIZABLE transaction.
- [FACT:fact_auth_token_v2] `auth_service` --(uses_token_format)--> `PASETO_v4_public` (valid_from=2026-04-20T16:45:00+00:00, src=ep_adr_019)
- [FACT:fact_ledger_isolation] `payment_ledger` --(requires_isolation_level)--> `SERIALIZABLE_WITH_IDEMPOTENCY_KEY` (valid_from=2026-03-01T11:15:00+00:00, src=ep_inv_007)
- [FACT:fact_order_depends_ledger] `order_repository` --(depends_on)--> `payment_ledger` (valid_from=2026-02-14T14:30:00+00:00, src=ep_bug_042)
==============================================================================

# Project-scoped:
claude mcp add --transport http cortex-mcp https://cortex-mcp-steel.vercel.app/mcp

# Global user-scoped (available across all projects):
claude mcp add --scope user --transport http cortex-mcp https://cortex-mcp-steel.vercel.app/mcp

{
  "mcpServers": {
    "cortex-mcp": {
      "type": "http",
      "url": "https://cortex-mcp-steel.vercel.app/mcp"
    }
  }
}

npx -y @smithery/cli install @codesphere-u/cortex-mcp --client claude

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/codesphere-u/cortex-mcp.git",
        "cortex-mcp",
        "serve-stdio"
      ]
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "memory_upsert_fact",
    "arguments": {
      "subject_id": "auth_service",
      "predicate": "signing_algorithm",
      "object_value": "Ed25519",
      "singular": true
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "memory_compile_context",
    "arguments": {
      "query": "authentication token signing and database transaction isolation",
      "max_tokens": 800
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "cortex_audit_contradictions",
    "arguments": {
      "auto_resolve": true
    }
  }
}

# 1. Audit active facts in the bi-temporal graph for logical/polarity contradictions
cortex-mcp audit-contradictions --json

# 2. Export compiled context packets as a TruthGate-compatible SourceDocument JSON bundle
cortex-mcp export-sources --query "auth_service uses_token_format" --output sources.json

from cortex_mcp import audit_contradictions, export_truthgate_sources

# Detect and auto-resolve cross-agent predicate alias or polarity conflicts
report = audit_contradictions(graph, auto_resolve=True)
print(report.summary_markdown)

# Export active facts with temporal provenance & SHA-256 Merkle root for codesphere-u/truthgate
sources = export_truthgate_sources(graph, query="payment_ledger isolation_level")

python -m cortex_mcp.cli benchmark

pytest -v

curl -s -X POST https://cortex-mcp-steel.vercel.app/mcp -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Add to current project:
claude mcp add --transport http cortex-mcp https://cortex-mcp-steel.vercel.app/mcp

# Or add globally across all projects:
claude mcp add --scope user --transport http cortex-mcp https://cortex-mcp-steel.vercel.app/mcp

{
  "mcpServers": {
    "cortex-mcp": {
      "type": "http",
      "url": "https://cortex-mcp-steel.vercel.app/mcp"
    }
  }
}