Skip to content
BranchesTags

Repository files navigation

🌌 Continuum — Persistent Graph Memory Server for Antigravity IDE

CI Pipeline License: MIT MCP Version TypeScript Benchmark Grade 7-Layer Tests

Unbroken, permanent continuity of memory across AI development sessions.

Continuum (@continuum/mcp-graph-memory) is a high-performance Model Context Protocol (MCP) server that provides Antigravity IDE with a persistent, deterministic Neo4j knowledge graph. It completely resolves AI context-window amnesia by structuring sessions, events, decisions, tasks, entities, and weekly milestones into an indexed property graph without making any external AI/LLM API calls.

🌟 Key Highlights

  • 🧠 Zero External AI Dependency: 100% deterministic rule engine (regex tokenizers, heuristic AST parsers, topological sorters, Cypher index traversal).
  • 🔒 Local-First & Secure: All graph data stays within your local Neo4j container or zero-dependency in-memory graph engine. No data ever leaves your machine.
  • ⚡ Ultra-Low Latency (A+ Production Elite): 11,000+ ops/sec for decisions, sub-2ms event ingestion, and sub-10ms 2-hop graph context retrieval.
  • 📐 Strict Graph Ontology: 6 strongly typed Node labels (Session, Event, Decision, Task, Entity, Milestone) and 7 relationship types (CAUSED, RESULTED_IN, PART_OF, REFERS_TO, FOLLOWED_BY, BELONGS_TO, SUMMARIZES).
  • 🛡️ Orphan Prevention & Timeline Invariants: Guarantees zero orphaned nodes and automatically chains consecutive session events via FOLLOWED_BY.
  • 🗺️ Visual Weekly Roadmaps: Computes weekly rollups and generates structured summaries accompanied by interactive Mermaid timeline & dependency diagrams.
  • 🧪 7-Layer Quality Assurance: Comprehensive automated test matrix covering Unit, Integration, Schema Invariants, MCP Protocol, E2E, Performance, and Resilience.

🏛️ System Architecture

graph TD
    subgraph AntigravityIDE["Antigravity IDE"]
        Agent["Antigravity Model / Agent"]
        MCPClient["MCP Client Protocol Stdio"]
    end

    subgraph ContinuumServer["Continuum MCP Server"]
        StdioTransport["Stdio Transport Handler"]
        ToolRouter["Protocol Handlers & Zod Validator"]
        
        subgraph RuleEngine["Deterministic Rule Engine"]
            EntityExtractor["Regex & Heuristic Entity Extractor"]
            Deduplicator["Entity Normalizer & Dedup Engine"]
            TimelineRules["Timeline Order & Chaining Manager"]
            MilestoneRules["Weekly Milestone Rollup Synthesizer"]
        end

        subgraph GraphEngine["Graph Memory Engine"]
            MemoryService["Memory Service Coordinator"]
            ContextRetriever["2-Hop Subgraph Context Retriever"]
            RoadmapGen["Mermaid Roadmap Generator"]
            CypherBuilder["Cypher Query Builder"]
        end

        subgraph Adapters["Database Adapters"]
            Neo4jAdapter["Neo4j Driver Connection Pool"]
            InMemoryAdapter["In-Memory Graph Engine"]
        end
    end

    subgraph StorageTier["Storage Tier"]
        Neo4jDB[("Neo4j 5.x Graph DB")]
        LocalMemory[("In-Memory Graph State")]
    end

    Agent <--> MCPClient
    MCPClient <--> StdioTransport
    StdioTransport <--> ToolRouter
    ToolRouter <--> MemoryService
    MemoryService --> EntityExtractor
    MemoryService --> Deduplicator
    MemoryService --> TimelineRules
    MemoryService --> MilestoneRules
    MemoryService --> ContextRetriever
    MemoryService --> RoadmapGen
    MemoryService --> CypherBuilder
    CypherBuilder --> Neo4jAdapter
    CypherBuilder --> InMemoryAdapter
    Neo4jAdapter <--> Neo4jDB
    InMemoryAdapter <--> LocalMemory
Loading

🚀 Quickstart

1. Installation

# Clone the repository
git clone https://github.com/vikrant-project/continuum-mcp.git
cd continuum-mcp

# Install dependencies
npm install

# Build TypeScript production bundle
npm run build

2. Start Storage Engine

# Option A: Start Neo4j via Docker Compose (Recommended)
docker-compose up -d

# Option B: Run in-memory (zero-dependency)
npm run init -- --engine inmemory

3. Initialize Graph Schema Constraints

npm run init -- --uri bolt://localhost:7687 --user neo4j --password continuumpassword

🔌 Antigravity IDE Configuration

Add Continuum to your mcp_config.json or Antigravity IDE settings:

{
  "mcpServers": {
    "continuum": {
      "command": "node",
      "args": ["d:/brain/dist/bin/continuum-mcp.js", "serve"]
    }
  }
}

🛠️ MCP Tool Catalog (7 Core + Operational Tools)

Tool Name Parameters Description
memory_start_session title, metadata Initializes a new work session, creating a root Session node.
memory_end_session sessionId Marks a session as completed, recording the conclusion timestamp.
memory_write_event sessionId, summary, type, causedByEventId, relatedEntities Records an event, links it to session, chains timeline, and links entities.
memory_write_decision sessionId, summary, reason, resultingEventId, relatedEntities Logs a architectural or technical decision and links causal outcome.
memory_create_task title, status, parentTaskId, sessionId Creates a task or subtask tree node.
memory_query_context topic, limit Performs 2-hop Cypher traversal returning ranked subgraph and markdown summary.
memory_get_timeline sessionId Retrieves chronological DAG of all events, decisions, and relationships in session.
memory_get_weekly_roadmap none Generates a multi-week roadmap with milestones and visual Mermaid diagrams.
memory_search_entity name Finds entity by normalized name or alias and lists all referencing nodes.
memory_get_stats none Returns comprehensive node and relationship counts across graph memory.

🖥️ CLI Commands Reference

Continuum includes a full CLI suite (continuum-mcp):

# Start MCP server over stdio
continuum-mcp serve

# Initialize graph schema & verify connectivity
continuum-mcp init --uri bolt://localhost:7687 --user neo4j --password continuumpassword

# Check real-time database connection and graph node statistics
continuum-mcp status

# Run full performance & latency benchmark suite
continuum-mcp benchmark --iterations 1000

# Export complete graph database snapshot to JSON
continuum-mcp backup --output ./backup.json

🧪 7-Layer Test Suite Matrix

Continuum follows a strict 7-layer verification strategy. All 18 test suites and 40 individual tests run continuously in CI:

npm test
 ✓ tests/layer1-unit/config.test.ts (2 tests)
 ✓ tests/layer1-unit/cypher-builder.test.ts (4 tests)
 ✓ tests/layer1-unit/deduplication.test.ts (3 tests)
 ✓ tests/layer1-unit/entity-extractor.test.ts (5 tests)
 ✓ tests/layer2-integration/adapter-transactions.test.ts (1 test)
 ✓ tests/layer2-integration/connection-lifecycle.test.ts (1 test)
 ✓ tests/layer3-schema/orphan-rejection.test.ts (3 tests)
 ✓ tests/layer3-schema/relationship-invariants.test.ts (3 tests)
 ✓ tests/layer3-schema/schema-constraints.test.ts (2 tests)
 ✓ tests/layer4-mcp/error-contracts.test.ts (3 tests)
 ✓ tests/layer4-mcp/tool-definitions.test.ts (1 test)
 ✓ tests/layer4-mcp/tool-execution.test.ts (3 tests)
 ✓ tests/layer5-e2e/multi-session-e2e.test.ts (2 tests)
 ✓ tests/layer5-e2e/weekly-roadmap-e2e.test.ts (1 test)
 ✓ tests/layer6-performance/concurrency.test.ts (1 test)
 ✓ tests/layer6-performance/load-scaling.test.ts (1 test)
 ✓ tests/layer7-resilience/failure-recovery.test.ts (2 tests)
 ✓ tests/layer7-resilience/graceful-degradation.test.ts (2 tests)

 Test Files  18 passed (18)
      Tests  40 passed (40)

⚡ Performance Benchmarks (Score: 100% | Grade: A+)

Run the benchmark suite:

npm run benchmark
========================================================================================
⚡ CONTINUUM MCP GRAPH MEMORY — PERFORMANCE & LATENCY BENCHMARKS
========================================================================================
Timestamp: 2026-08-15T13:27:21.734Z
Overall Rating: A+ (Production Elite) [Score: 100%]

| Benchmark Operation                             | Ops/Sec | p50 (ms) | p95 (ms) | p99 (ms) | Status |
|-------------------------------------------------|---------|----------|----------|----------|--------|
| Event Ingestion + Entity Linking + Timeline Chaining |    1179 |   0.82ms |    1.7ms |   2.13ms |   PASS   |
| Decision Writing + Deduplication + Causal Linking |   11212 |   0.06ms |   0.16ms |   0.43ms |   PASS   |
| 2-Hop Subgraph Context Retrieval & Expansion    |     175 |   4.84ms |   9.95ms |  20.46ms |   PASS   |
| Chronological Session Timeline Traversal        |     973 |    0.9ms |   1.44ms |   3.34ms |   PASS   |
| Weekly Milestone Aggregation & Roadmap Synthesis |     451 |   2.03ms |   3.56ms |   6.56ms |   PASS   |
========================================================================================

📚 Documentation

📜 License

MIT License. Designed and engineered for Antigravity IDE and modern AI pair-programming workflows.

About

Continuum: Persistent Neo4j Knowledge Graph Memory MCP Server for Antigravity IDE

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages