pip install exogram
# Or install directly from source:
pip install git+https://github.com/Richard-Ewing/exogram-sdk.git

from exogram import ExogramClient

# Automatically initializes ~/.exogram/vault.db (SQLite WAL) when no API key is set,
# or routes to https://api.exogram.ai when api_key="exo_live_..." or EXOGRAM_API_KEY is set.
client = ExogramClient()

# 1. Store memory claims across Work, People, and Life spheres
record = client.vault.store(
    "Architecture decision: Production edge deploys to Cloudflare Workers via OpenNext",
    namespace="work",
    sphere="Work",
    confidence=0.98,
    temporal_horizon="durable_trait",
)
print(f"Stored {record.id} | State Hash: {record.state_hash}")

# 2. Traverse the Personal Neural Network (Infinite-Hop Spreading Activation + HippoRAG 2 PPR)
context = client.neural_network.retrieve(
    query="How does our production edge deploy?",
    spheres=["Work", "People", "Life"],
    max_hops=4,
)
print(f"PPR Converged: {context.ppr_converged} | Claims: {len(context.claims)}")

# 3. Deterministic 0.07ms State-Hash & Instinct Pre-Mutation Action Gate
judgment = client.governance.evaluate_action(
    agent_id="deployment-sentinel",
    action_type="deploy_cloudflare_worker",
    parameters={"service": "exogram-edge", "environment": "production"},
    state_hash=context.state_hash,
)

if judgment.permitted:
    receipt = client.actions.execute(judgment.execution_token)
    print(f"Committed! Ledger Hash: {receipt.ledger_hash}")

python examples/quickstart_local_and_cloud.py

{
  "mcpServers": {
    "exogram": {
      "command": "uvx",
      "args": ["mcp-server-exogram", "--local"]
    }
  }
}

{
  "mcpServers": {
    "exogram": {
      "command": "uvx",
      "args": ["mcp-server-exogram"],
      "env": {
        "EXOGRAM_API_KEY": "exo_live_your_key_here",
        "EXOGRAM_API_URL": "https://api.exogram.ai"
      }
    }
  }
}

npm install @exogram/sdk

import { ExogramClient } from '@exogram/sdk';

const client = new ExogramClient(); // Zero-signup local mode or pass { apiKey: process.env.EXOGRAM_API_KEY }

const rec = await client.vault.store('Deploy target is Cloudflare Workers Global Edge', {
  namespace: 'work',
  sphere: 'Work',
  confidence: 0.96,
});

const context = await client.neuralNetwork.retrieve('What is our deploy target?', {
  spheres: ['Work', 'People', 'Life'],
  maxHops: 4,
});

const judgment = await client.governance.evaluateAction({
  agentId: 'ts-agent',
  actionType: 'deploy_worker',
  parameters: { target: 'cloudflare' },
  stateHash: context.stateHash,
});

if (judgment.permitted && judgment.executionToken) {
  const receipt = await client.actions.execute(judgment.executionToken);
  console.log('Committed Ledger Hash:', receipt.ledgerHash);
}

┌──────────────────────────────────────────────────────────────────────────────┐
│                     User Prompt / External MCP Agent Call                    │
└──────────────────────────────────────┬───────────────────────────────────────┘
                                       ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│ 1. Laya System 1 Deterministic Fast-Path (<15ms In-Memory Understanding)     │
│    Resolves vault subjects, intent, sphere routing (Work · People · Life),   │
│    and search queries in <15ms over profileDigest + priorTurns.              │
└──────────────────────────────────────┬───────────────────────────────────────┘
                                       ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│ 2. Personal Neural Network (Infinite-Hop Spreading Activation + HippoRAG 2)  │
│    • Hybrid RRF Retrieval (Vector + BM25 + Entity Overlap)                   │
│    • Personalized PageRank (PPR, damping α = 0.85) across multi-hop edges    │
│    • 3-Horizon Episodic Memory (ephemeral_episode, recurring_event, durable) │
│    • Read-Time/Write-Time Scalar Conflict Supersession & /api/memory/undo    │
└──────────────────────────────────────┬───────────────────────────────────────┘
                                       ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│ 3. Two-Tier Inference Gateway & 6 Honest First-Party Kernels                 │
│    • PERSONAL Subtasks → Paid Gemini 3.x (Zero PII leaves encrypted boundary)│
│    • PUBLIC_ONLY Subtasks → PII-stripped & compressed before Free-Token Pool │
│    • Post-Synthesis Citation Verification (Complete · Cited vs Standby)      │
└──────────────────────────────────────┬───────────────────────────────────────┘
                                       ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│ 4. Instinct Pre-Mutation Governance (0.07ms Gate) & A2UI Living Tiles        │
│    • Deterministic SHA-256 State-Hash Drift Guard before any tool mutation   │
│    • Progressive JSON Patching (AG-UI) & Claim-Predicate Entailment Scoring  │
└──────────────────────────────────────────────────────────────────────────────┘

exogram-sdk/
├── python/                  # Official Python SDK (pip install exogram)
├── typescript/              # Official TypeScript SDK (npm install @exogram/sdk)
├── mcp-server/              # FastMCP Server (uvx mcp-server-exogram)
├── schemas/                 # JSON Schemas (living-tiles-v5.schema.json)
├── examples/                # Runnable Local & Cloud Quickstart scripts
└── docs/assets/             # Plum Mineral UI previews & architecture diagrams

# 1. Run the 60-second quickstart script
python examples/quickstart_local_and_cloud.py

# 2. Run Python SDK unit tests
pytest python/tests/

# 3. Run FastMCP Server unit tests
pytest mcp-server/tests/

# 4. Run TypeScript SDK unit tests
cd typescript && npm test