suma-mcp-proxy

SUMA MCP Proxy

Persistent AI memory for Claude Code, Cursor, and any MCP-compatible IDE

Your AI forgets everything when a session ends. SUMA gives it a permanent knowledge graph — so it remembers who you are, what you're building, and every decision you've made.

┌─────────────────────────────────────────────────────────────────────┐
│  Your IDE (Claude Code / Cursor / Windsurf)                         │
│  ┌───────────────┐     stdio      ┌────────────────────────────┐   │
│  │ AI Assistant  │◄──────────────►│ suma-mcp-proxy (local)     │   │
│  └───────────────┘   (stable)     └─────────────┬──────────────┘   │
└─────────────────────────────────────────────────┼───────────────────┘
                                                  │ HTTPS
                                                  ▼
                              sumapro.quadframe.work
                              ┌────────────────────────────────────┐
                              │  K-WIL Gravity Engine              │
                              │  PostgreSQL + pgvector             │
                              │  Gemini embeddings                 │
                              └────────────────────────────────────┘

Quick Start

1. Get your API key

Sign up free at sumapro.quadframe.work

2. Verify it works (optional but recommended)

npx suma-mcp-proxy@latest --key=sk_live_YOUR_KEY

You should see:

SUMA MCP Proxy v1.3.5 started
Org ID: your_org | Tier: free
Ready.

Press Ctrl+C to stop. If this works, installation will work.

3. Add to your project

Create .mcp.json in your project root:

{
  "mcpServers": {
    "suma-memory": {
      "command": "npx",
      "args": ["suma-mcp-proxy", "--key=sk_live_YOUR_KEY"]
    }
  }
}

No global install needed. Claude Code reads .mcp.json on startup and runs the proxy automatically via npx — every session, zero maintenance.

4. Restart Claude Code or Cursor

SUMA starts learning automatically from your first session.

Available Tools

Tool	Description
suma_ping	Verify connection — call once at session start
suma_ingest	Store knowledge in the graph (auto entity extraction + embedding)
suma_search	Search with K-WIL Gravity Well Algorithm — returns ranked nodes + synthesized answer
suma_talk	Bidirectional — search AND learn in one call
suma_correct	Fix an incorrect node (soft delete, preserves audit trail)
suma_stats	Graph statistics + K-WIL token economics — the ROI receipt (node count, compression ratio, tokens saved)
suma_clean	Wipe all data for your org (requires confirmation)

Tool Examples

suma_ingest

{
  text: "Decided to use cosine² instead of (1+cosine) in K-WIL — 20x stronger signal separation",
  sphere: "architecture"  // optional — auto-classified if omitted
}
// Returns: { status: "ok", node_id: "ARCHITECTURE_abc123", compression: "94%" }

suma_search

{
  query: "why did we choose PostgreSQL over MongoDB",
  limit: 5
}
// Returns: { answer: "...", results: [...nodes...], entities: [...], token_economics: {...} }

suma_talk

{
  message: "We just decided to use PostgreSQL with pgvector instead of Pinecone"
}
// Returns: { answer: "...", nodes_learned: 2 }
// Searches graph for context AND ingests the new decision in one call.

suma_stats

{}  // no arguments
// Returns: { node_count: 521, compression_ratio: "97.6%", tokens_saved_lifetime: 4263729,
//            tier: "enterprise", spheres: { architecture: 120, work: 62, ... } }
// Show this to the user as the ROI receipt.

suma_correct

{
  node_id: "FAMILY_783e4d5623e0",
  reason: "Chinni is wife's nickname, not mother",
  replacement_text: "Chinni is Suman's nickname for his wife Madhuri"
}

How It Works

Why a local proxy?

MCP uses stdio — it's designed for local connections, not cloud APIs. Direct cloud connections drop when:

• Service scales to zero between calls
• New version deploys mid-session
• Network hiccup breaks the stdio pipe

The proxy runs locally, maintaining a stable stdio connection to your IDE while making stateless HTTPS calls to the cloud. Your IDE never knows the difference.

K-WIL Algorithm

Every search runs the K-WIL Gravity Well Algorithm across your knowledge graph:

Gravity = V × H × M × L × T

Factor	What It Does
V (Vector Hit)	Cosine similarity between your query and node embedding — semantic match
H (Entity Group)	Harmonic mean weight of entity pairs linked to this node — relational signal
M (Node Bridge)	Confidence weight of entity-node links — extraction quality signal
L (Dedup Boost)	1 + log10(1 + hit_count) — nodes seen many times rank higher
T (Time Decay)	1 / (1 + days_old) — recent memories rank higher; permanent facts bypass decay

Path 2 safety: if no entity data exists yet (new node), H and M default to 1.0 — search falls back to pure vector similarity gracefully. Full 5-factor precision kicks in the moment entities are extracted.

Result: Retrieval Precision — your graph may have 180K tokens of knowledge. A single search retrieves the exact 800 tokens Claude needs. No more, no less.

Ambient Auto-Onboarding

On first run in a new project, the proxy silently reads:

• git config user.name and user.email
• Workspace type (detected from package.json, pubspec.yaml, etc.)
• First 500 chars of your README.md

It ingests a lightweight project seed so Claude immediately knows your context. Use --no-scan to disable.

Spheres (Knowledge Categories)

Nodes are automatically classified into spheres that shape retrieval ranking:

Sphere	What goes here
architecture	System design, API contracts, architectural decisions
work	Tasks, deployments, code decisions
technology	Stack choices, tools, integrations
vision	Goals, product strategy, business direction
family	Personal relationships
health	Medical, wellness
personal	Personal notes and preferences

Pass sphere explicitly to override auto-classification.

Environment Variables

Variable	Description	Default
SUMA_API_KEY	Your API key (sk_live_...) — required	—
SUMA_API_URL	Override API endpoint	https://sumapro.quadframe.work

Privacy

• Your data is isolated by org_id — no other user can access your graph
• The proxy reads git identity and README on first boot only (use --no-scan to disable)
• No telemetry sent beyond your own SUMA server
• You can wipe all data at any time: suma_clean({ confirm: true })

Changelog

v1.4.0 (April 17, 2026)

• Omni-Brain Architecture — org_types TEXT[] allows one org to simultaneously span multiple industry profiles (personal + enterprise). All sphere vocabularies union automatically.
• Stackable Personas — selected_personas TEXT[] replaces single is_active persona. Stack forensics + analyst simultaneously; extraction engine unions their vocabularies.
• Dual-Axis Ontology — Axis 1: sphere floor (content-determined, hard gate). Axis 2: persona extras (intent-determined, additive union). Entity extraction constrained to sphere.allowed ∪ persona.extra ∪ persona.learned.
• Active Sleep Phase 5 — Neuroplastic vocabulary promotion. Entity types appearing 3+ times are promoted to the active persona's learned_entity_types. Targeted scoring prevents persona vocabulary collapse.
• suma_stats omni_brain block — suma_stats now returns org_types, selected_personas, sphere_distribution, entity_counts, edge_count for full graph telemetry.
• K-WIL updated to 2-Path Convergence (V×H×M×L×T) — see formula above.

v1.3.5 (April 9, 2026)

• Mock OAuth port — default moved to 5556 (5555 reserved by Android emulator ADB)
• suma_stats tool — added to proxy; returns node count, sphere breakdown, compression ratio, tokens saved lifetime. The ROI receipt.
• Block 3 E2E tests — full SSO pipeline test suite added (test_companion_memory_e2e.spec.js)

v1.3.4 (April 9, 2026)

• K-WIL fidelity baseline sealed — 96.3% (26/27 facts recoverable) on fresh 5-node graph
• Temporally-anchored search — proxy now supports explicit keyword anchoring for historical queries

v1.3.3 (April 9, 2026)

• Life story seed — scripts/seed_life_story.py — 58 temporally-anchored nodes (Apr 2025–Apr 2026)
• 58-test Playwright E2E suite — production_hardening + kwil_fidelity + dashboard_session all passing

v1.3.2 (April 9, 2026)

• Semantic edge weight taxonomy — Gemini scores each extracted relationship using a 5-tier gravity model (action=0.90, work=0.65, spatial=0.40). recompute_node_harmonic_weight() carries true semantic variance. CREATED edges contribute 2.25× more gravitational mass than LIVES_IN edges.
• Gate 2 response now includes similarity, harmonic_weight, reinforcement fields — AI clients know when near-duplicate content strengthened an existing node vs created a new one.

v1.3.0 (April 6, 2026)

• Ambient auto-onboarding on first boot per project
• --no-scan flag for privacy-conscious developers
• Client-side persona weight injection

v1.2.0 (April 5, 2026)

• Production URL: sumapro.quadframe.work

v1.1.0 (April 5, 2026)

• Added suma_correct tool

v1.0.0

• Initial release: ping, ingest, search, talk, clean

Support

• Dashboard: sumapro.quadframe.work
• Email: [e-mail]

License

MIT — Suman Addanke / A2 Vibe Creators LLC