Exogram Sdk MCP Server

Exogram Open-Core SDK & FastMCP Server (v0.2.0)

Exogram (exogram.ai) is a Personal AI Agent and workspace that understands your whole story across your work, people, and everyday life—coordinating specialist agents, turning plain requests into finished interactive deliverables, and executing real tasks with your approval.

This open-core repository provides the official Python/TypeScript SDKs and MCP bridge (mcp-server-exogram) so external AI tools (Claude, Cursor, Windsurf, VS Code, Google Antigravity) can connect directly into that same Exogram Personal Neural Network, interactive widget engine, and action-approval guardrails.

This open-core repository ships the runnable client libraries, local SQLite WAL engine, FastMCP server, and A2UI Living Tile JSON schemas:

• python/ (exogram v0.2.0) — Python SDK with Zero-Signup Local SQLite WAL Mode (~/.exogram/vault.db) and Cloud API routing (https://api.exogram.ai).
• typescript/ (@exogram/sdk v0.2.0) — TypeScript & Node.js SDK with CJS/ESM/DTS builds and zero-signup local mode.
• mcp-server/ (mcp-server-exogram v0.2.0) — FastMCP Server for Claude Desktop, Cursor, Google Antigravity, and OpenAI Agents.
• schemas/living-tiles-v5.schema.json — Canonical JSON Schema for all Composable A2UI Living Tiles and the 6 First-Party Kernels.

---

60-Second Zero-Signup Quickstart (Local SQLite WAL & Cloud)

Every SDK and MCP tool runs immediately on your machine using an embedded SQLite WAL vault (~/.exogram/vault.db) with zero account signup or API key required. When you set EXOGRAM_API_KEY, the exact same code routes to Exogram Cloud (https://exogram.ai).

1. Run the Python SDK in 30 Seconds

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}")

Or run the self-contained demo script directly from this repository:

python examples/quickstart_local_and_cloud.py

2. Connect Claude Desktop, Cursor, or Antigravity via FastMCP (<30s)

Option A: Zero-Signup Local SQLite WAL Mode (~/.exogram/vault.db)

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

Option B: Hosted Exogram Cloud MCP (https://exogram.ai/api/mcp)

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

3. TypeScript / Node.js Quickstart (@exogram/sdk)

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);
}

---

Architecture Overview (Master Plan v5)

┌──────────────────────────────────────────────────────────────────────────────┐
│                     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  │
└──────────────────────────────────────────────────────────────────────────────┘

The 6 First-Party Cognitive Kernels

Every turn is orchestrated by six specialized first-party kernels and audited by verifyAgentContributionsAgainstTurnOutput so only kernels whose outputs are genuinely cited in the final synthesis display Complete · Cited:

Composable A2UI Living Tiles (schemas/living-tiles-v5.schema.json)

Exogram dispatches structured inline Living Tiles validated for epistemic provenance:

• action_draft — Governed outbound drafts (email, message, calendar, PR) with approval controls.
• checklist — Interactive execution checklists anchored to vault goals.
• decision_matrix — Multi-criteria weighted scoring tables.
• curated_places — Grounded venue & location cards with verified ratings.
• comparison_table — Side-by-side technical or product breakdowns.
• retail_deals_tile — Verified merchant pricing and availability cards.
• media_watch_tile — Film, series, book, and podcast recommendations with streaming provenance.
• occasion_countdown_tile — Recurring event (RRULE:FREQ=YEARLY) countdowns and preparation steps.
• memory_undo_tile — Transparent memory consolidation card with one-click /api/memory/undo.
• agent_hud_tile — Real-time telemetry of the 6 First-Party Kernels (Complete · Cited vs Standby).
• branded_diagram_tile — Publication-grade Plum Mineral (#FAF7F2, #201B20, #4C2B4B, #AEBD9A) SVG diagrams.
• hyperframes_video_tile — Frame-accurate deterministic HTML/CSS/SVG motion briefings (window.__renderFrame).
• instinct_computer_tile — Stateful browser/errand operator HUD with Approve Step and Take Over controls.

---

Repository Structure & Verification

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

Run the Test Suites Locally

# 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

License

MIT — see LICENSE for details.