How do I install Semantic Wake Intelligence?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Semantic Wake Intelligence need an API key?

No required environment variable is listed on this record.

What transport does Semantic Wake Intelligence use?

Semantic Wake Intelligence runs locally over stdio.

Semantic Wake Intelligence MCP 服务器

Q: When was Semantic Wake Intelligence last checked?

Last checked 2026-10-28. Wake Intelligence: 5-Layer Temporal Intelligence for AI Agents A production-ready Model Context Protocol (MCP) server implementing a temporal intelligence "brain" with five layers: Past (causality tracking), Present (memory management), Future (predictive pre-fetching), Adaptive (meta-learning — per-project weight tuning), and Personality (tempora

Wake Intelligence MCP

Wake Intelligence: 5-Layer Temporal Intelligence for AI Agents

A production-ready Model Context Protocol (MCP) server implementing a temporal intelligence "brain" with five layers: Past (causality tracking), Present (memory management), Future (predictive pre-fetching), Adaptive (meta-learning — per-project weight tuning), and Personality (temporal postures that shape how context is retrieved and presented).

Reference implementation of Semantic Intent as Single Source of Truth patterns with hexagonal architecture.

What's New in v3.7.0

Agent Task Coordination

A multi-agent work queue built directly into Wake — any model (Claude session, local LLM, Ollama, custom script) can claim tasks and save discoveries back as causal context. Intended for token-expensive work (heavy log parsing, large backtests, diagnostic sweeps) that runs cheaper off the main session.

create_task — Enqueue an objective for an agent to work on
claim_task — Atomically claim the next queued task for a given agent ID (safe under concurrent workers)
get_tasks — List tasks filtered by project, status, or assigned agent
complete_task — Mark a task done and link the result context IDs
fail_task — Record a failure reason for visibility and retry logic

See wake-worker/ in this repo for a ready-to-run headless worker that authenticates via Signet client_credentials and polls for tasks.

Total: 24 MCP tools, 5 personality modes, 265 tests.

Previous: v3.6.0

Semantic Search Quality + Admin Reindex

Vectorize results below 0.6 cosine similarity are filtered — eliminates false positives
search_context tokenizes queries on meaningful words (3+ chars) so single-char queries and long natural-language phrases both route correctly
admin_reindex_all — Cross-project backfill that embeds all D1 contexts into Vectorize in one call; run once after setup or after a dry Vectorize index

Previous: v3.5.0

Observability + Rune Protocol Integration

get_causal_graph — Full causal network as nodes + edges, ready for D3/Mermaid visualization
get_memory_health — All 5 layers in one diagnostic call (replaces 4–5 separate tool calls)
ingest_rune_manifest — Import a rune.schema.json manifest; each ? intent annotation becomes a Wake causal memory entry
auditor personality mode — Groups contexts by author type: human, ai-agent, ai-compositor, unattributed
authorType on save_context — Governance attribution stored in metadata.authorType, readable by auditor mode and causal graph

🧠 Wake Intelligence Brain Architecture

Wake Intelligence implements a 5-layer temporal intelligence system that learns from the past, manages the present, predicts the future, adapts its own prediction weights, and shapes how context is surfaced:

Layer 1: Causality Engine (Past - WHY)

Tracks WHY contexts were created and their causal relationships.

Features:

✅ Causal chain tracking (what led to what)
✅ Dependency auto-detection from temporal proximity
✅ Reasoning reconstruction ("Why did I do this?")
✅ Action type taxonomy (decision, implementation, refactor, etc.)

Use Cases:

Trace decision history backwards through time
Understand why a context was created
Identify context dependencies automatically
Reconstruct reasoning from past sessions

Layer 2: Memory Manager (Present - HOW)

Manages HOW relevant contexts are right now based on temporal patterns.

Features:

✅ 4-tier memory classification (ACTIVE, RECENT, ARCHIVED, EXPIRED)
✅ LRU tracking (last access time + access count)
✅ Automatic tier recalculation based on age
✅ Expired context pruning

Memory Tiers:

ACTIVE: Last accessed < 1 hour ago
RECENT: Last accessed 1-24 hours ago
ARCHIVED: Last accessed 1-30 days ago
EXPIRED: Last accessed > 30 days ago

Use Cases:

Prioritize recent contexts in search results
Automatically archive old contexts
Prune expired contexts to save storage
Track context access patterns

Layer 3: Propagation Engine (Future - WHAT)

Predicts WHAT contexts will be needed next for proactive optimization.

Features:

✅ Composite prediction scoring (40% temporal + 30% causal + 30% frequency)
✅ Pattern-based next access estimation
✅ Observable prediction reasoning
✅ Staleness management with lazy refresh
✅ Proactive background refresh via scheduled cron (every 6 hours, all projects)

Prediction Algorithm:

Temporal Score (40%): Exponential decay based on last access time
Causal Score (30%): Position in causal chains (roots score higher)
Frequency Score (30%): Logarithmic scaling of access count

Use Cases:

Pre-fetch high-value contexts for faster retrieval
Cache frequently accessed contexts in memory
Prioritize contexts by prediction score
Identify patterns in context usage

Layer 4: Meta-Learning Engine (Adaptive - HOW WELL)

Tunes HOW WELL predictions work by learning from observed access patterns per project.

Features:

✅ Per-project weight tuning from real access outcomes
✅ Activates after ≥20 outcomes — defaults to 40/30/30 until then
✅ Weights clamped [0.1, 0.6] — no single dimension can dominate
✅ get_learning_stats tool — inspect current weights and component averages

Weight Dimensions:

Temporal (default 40%): How recently was this context accessed?
Causal (default 30%): How central is it in causal chains?
Frequency (default 30%): How often has it been accessed?

Use Cases:

Let the system discover that causal position predicts access better than recency on long-running projects
Inspect per-project learning progress with get_learning_stats
Weights feed directly into Prophet mode ranking

Layer 5: Personality Modes (Presentation - HOW SURFACED)

Shapes HOW context is retrieved and presented via four temporal postures on load_context and search_context.

Modes:

✅ historian (default) — newest-first, timestamps, causality action type and rationale
✅ prophet — ranked by Layer 4 prediction score; surfaces what you'll likely need next
✅ archaeologist — most-dormant first (never-accessed sorted to top); resurfaces forgotten threads
✅ minimalist — raw summaries only, no framing or metadata
✅ auditor (v3.5.0) — groups contexts by author type: 👤 Human, 🤖 AI Agent, 🎼 AI Compositor, ❓ Unattributed

Use Cases:

Re-entering a project after a long gap → archaeologist to find forgotten threads
Planning the next session → prophet to see what Layer 4 predicts you'll need
Scripted/automated consumers → minimalist for clean output
Default session continuity → historian for full decision context
Governance review → auditor to see which decisions were human vs. AI-originated

Temporal Intelligence Flow:

┌─────────────────────────────────────────────────────────────┐
│                   WAKE INTELLIGENCE BRAIN                    │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  LAYER 5: PERSONALITY MODES (Presentation - HOW SURFACED)  │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ • historian     — newest-first, timestamps, causality    │    │
│  │ • prophet       — ranked by Layer 4 prediction score    │    │
│  │ • archaeologist — most-dormant contexts first            │    │
│  │ • minimalist    — raw summaries, no framing              │    │
│  │ • auditor       — grouped by author type (human/AI)      │    │
│  └─────────────────────────────────────────────────────┘    │
│                            ▲                                  │
│  LAYER 4: META-LEARNING ENGINE (Adaptive - HOW WELL)        │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ • Tunes per-project prediction weights              │    │
│  │ • Learns from access outcomes (≥20 samples)         │    │
│  │ • Clamps weights [0.1, 0.6] — no dimension dominates│    │
│  └─────────────────────────────────────────────────────┘    │
│                            ▲                                  │
│  LAYER 3: PROPAGATION ENGINE (Future - WHAT)                │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ • Predicts WHAT will be needed next                 │    │
│  │ • Composite scoring (temporal + causal + frequency) │    │
│  │ • Pre-fetching optimization                         │    │
│  └─────────────────────────────────────────────────────┘    │
│                            ▲                                  │
│  LAYER 2: MEMORY MANAGER (Present - HOW)                    │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ • Tracks HOW relevant contexts are NOW              │    │
│  │ • 4-tier memory classification                      │    │
│  │ • LRU tracking + automatic tier updates             │    │
│  └─────────────────────────────────────────────────────┘    │
│                            ▲                                  │
│  LAYER 1: CAUSALITY ENGINE (Past - WHY)                     │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ • Tracks WHY contexts were created                  │    │
│  │ • Causal chain tracking + cross-project dependents  │    │
│  │ • Dependency auto-detection                         │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                               │
└─────────────────────────────────────────────────────────────┘

Benefits:

🎯 Learn from the past: Understand causal relationships across projects
🎯 Optimize the present: Manage memory intelligently
🎯 Predict the future: Pre-fetch what's needed next
🎯 Adapt continuously: Per-project weights improve with every access
🎯 Surface intelligently: Personality modes shape what you see and when
🎯 Observable reasoning: Every decision is explainable

🎯 What Makes This Different

This isn't just another MCP server—it's a reference implementation of proven semantic intent patterns:

✅ Semantic Anchoring: Decisions based on meaning, not technical characteristics
✅ Intent Preservation: Semantic contracts maintained through all transformations
✅ Observable Properties: Behavior anchored to directly observable semantic markers
✅ Domain Boundaries: Clear semantic ownership across layers

Built on research from Semantic Intent as Single Source of Truth, this implementation demonstrates how to build maintainable, AI-friendly codebases that preserve intent.

🚀 Quick Start

Prerequisites

Node.js 20.x or higher
Cloudflare account (free tier works)
Wrangler CLI: npm install -g wrangler

Installation

Clone the repository

git clone https://github.com/semanticintent/semantic-wake-intelligence-mcp.git
cd semantic-wake-intelligence-mcp

Install dependencies
```
npm install
```
Configure Wrangler

Copy the example configuration:
```
cp wrangler.jsonc.example wrangler.jsonc
```
Create a D1 database:
```
wrangler d1 create mcp-context
```
Update wrangler.jsonc with your database ID. The example also includes a triggers.crons entry for the Layer 3 scheduled prediction refresh (runs every 6 hours):
```
{
  "d1_databases": [{
    "database_id": "your-database-id-from-above-command"
  }],
  "triggers": {
    "crons": ["0 */6 * * *"]
  }
}
```

Run database migrations

# Local development
wrangler d1 execute mcp-context --local --file=./migrations/0001_initial_schema.sql

# Production
wrangler d1 execute mcp-context --file=./migrations/0001_initial_schema.sql

Start development server
```
npm run dev
```

Deploy to Production

npm run deploy

Your MCP server will be available at: semantic-wake-intelligence-mcp.<your-account>.workers.dev

📚 Learning from This Implementation

This codebase demonstrates semantic intent patterns throughout:

Architecture Files:

src/index.ts - Dependency injection composition root (74 lines)
src/domain/ - Business logic layer (ContextSnapshot, ContextService)
src/application/ - Orchestration layer (handlers and protocol)
src/infrastructure/ - Technical adapters (D1, AI, CORS)
src/presentation/ - HTTP routing layer (MCPRouter)

Documentation & Patterns:

migrations/0001_initial_schema.sql - Schema with semantic intent documentation
src/types.ts - Type-safe semantic contracts
SEMANTIC_ANCHORING_GOVERNANCE.md - Governance rules and patterns
REFACTORING_PLAN.md - Complete refactoring documentation

Each file includes comprehensive comments explaining WHY decisions preserve semantic intent, not just WHAT the code does.

Connect to Cloudflare AI Playground

You can connect to your MCP server from the Cloudflare AI Playground, which is a remote MCP client:

Go to https://playground.ai.cloudflare.com/
Enter your deployed MCP server URL (remote-mcp-server-authless.<your-account>.workers.dev/sse)
You can now use your MCP tools directly from the playground!

Connect Claude Desktop to your MCP server

Wake uses JWT auth via Signet — an OAuth 2.1 Authorization Server. The first connection triggers a one-time browser login (OTP email); subsequent connections use the cached refresh token automatically.

With mcp-remote (interactive/human clients):

{
  "mcpServers": {
    "wake": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://wake.shatny.dev/sse"
      ]
    }
  }
}

With a headless worker (automated agents):

Use client_credentials auth — no browser required. See wake-worker/ for a ready-to-run polling worker that fetches a token from Signet and connects via StreamableHTTPClientTransport.

cd wake-worker
echo "WORKER_AGENT_SECRET=<your-secret>" > .env
node --env-file=.env worker.mjs --test-auth   # verify auth
node --env-file=.env worker.mjs               # start polling

🏗️ Architecture

This project demonstrates Domain-Driven Hexagonal Architecture with clean separation of concerns:

┌─────────────────────────────────────────────────────────┐
│                   Presentation Layer                     │
│              (MCPRouter - HTTP routing)                  │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│                  Application Layer                       │
│     (ToolExecutionHandler, MCPProtocolHandler)          │
│              MCP Protocol & Orchestration                │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│                    Domain Layer                          │
│         (ContextService, ContextSnapshot)                │
│                 Business Logic                           │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│                Infrastructure Layer                      │
│    (D1ContextRepository, CloudflareAIProvider)          │
│           Technical Adapters (Ports & Adapters)         │
└─────────────────────────────────────────────────────────┘

Layer Responsibilities:

Domain Layer (src/domain/):

Pure business logic independent of infrastructure
ContextSnapshot: Entity with validation rules
ContextService: Core business operations

Application Layer (src/application/):

Orchestrates domain operations
ToolExecutionHandler: Translates MCP tools to domain operations
MCPProtocolHandler: Manages JSON-RPC protocol

Infrastructure Layer (src/infrastructure/):

Technical adapters implementing ports (interfaces)
D1ContextRepository: Cloudflare D1 persistence
CloudflareAIProvider: Workers AI integration
CORSMiddleware: Cross-cutting concerns

Presentation Layer (src/presentation/):

HTTP routing and request handling
MCPRouter: Routes requests to appropriate handlers

Composition Root (src/index.ts):

Dependency injection
Wires all layers together
74 lines (down from 483 - 90% reduction)

Benefits:

✅ Testability: Each layer independently testable
✅ Maintainability: Clear responsibilities per layer
✅ Flexibility: Swap infrastructure (D1 → Postgres) without touching domain
✅ Semantic Intent: Comprehensive documentation of WHY
✅ Type Safety: Strong TypeScript contracts throughout

Features

Core Context Management

save_context: Save conversation context with AI-powered summarization and auto-tagging; supports crossProject: true for cross-project dependency detection; authorType (human | ai-agent | ai-compositor) for governance attribution
load_context: Retrieve relevant context for a project — pass personality_mode to shape retrieval (see Layer 5)
search_context: Semantic vector search (Cloudflare Vectorize) with keyword fallback — pass personality_mode to re-rank results

Wake Intelligence Layer 1: Causality (Past)

reconstruct_reasoning: Understand WHY a context was created
build_causal_chain: Trace decision history backwards through time
get_causality_stats: Analytics on causal relationships and action types
get_cross_project_dependents: Find all downstream contexts (any project) caused by a given snapshot

Wake Intelligence Layer 2: Memory (Present)

get_memory_stats: View memory tier distribution and access patterns
recalculate_memory_tiers: Update tier classifications based on current time
prune_expired_contexts: Automatic cleanup of old, unused contexts

Wake Intelligence Layer 3: Propagation (Future)

update_predictions: Refresh prediction scores for a project
get_high_value_contexts: Retrieve contexts most likely to be accessed next
get_propagation_stats: Analytics on prediction quality and patterns

Wake Intelligence Layer 4: Meta-Learning (Adaptive)

get_learning_stats: View learned per-project weights and component averages
reindex_project: Backfill semantic embeddings for historical snapshots

Wake Intelligence Layer 5: Personality Modes (Presentation)

Five temporal postures available on load_context and search_context via the personality_mode param:

historian (default): Newest-first, timestamps, causality action type and rationale
prophet: Ranked by Layer 4 prediction score — surfaces what you are most likely to need next
archaeologist: Most-dormant contexts first (null lastAccessed sorted to top) — resurfaces forgotten threads
minimalist: Raw summaries only, no framing or metadata
auditor (v3.5.0): Groups results by author type — human, ai-agent, ai-compositor, unattributed

Wake Intelligence v3.5.0: Observability + Rune Integration

get_causal_graph: Full project causal network as { nodes, edges } — feed directly to D3 or Mermaid. Each node includes id, summary, actionType, memoryTier, timestamp, authorType
get_memory_health: Consolidated diagnostic report — all 5 layers in one call. Memory tiers + causality stats + prediction quality + learned weights
ingest_rune_manifest: Import a rune.schema.json manifest. Each binding with an intent (? rune annotation) is saved as a Wake context with action_type: decision and the intent as the rationale. Connects Rune Protocol governance declarations to Wake causal memory

Agent Task Coordination (v3.7.0)

create_task: Enqueue an objective for a named agent to work on, scoped to a project
claim_task: Atomically claim the next queued task (safe for concurrent workers — backed by UPDATE...WHERE subquery...RETURNING)
get_tasks: List tasks filtered by project, status, or assignedTo
complete_task: Mark a task done and attach result context IDs linking the discovery back to Wake's causal graph
fail_task: Record a failure reason — visibility for retry logic or human review

🧪 Testing

This project includes comprehensive unit tests with 265 tests covering all architectural layers.

Run Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui

# Run tests with coverage report
npm run test:coverage

Test Coverage

✅ Domain Layer: 146 tests (ContextSnapshot, CausalityService, ContextService, MemoryManagerService, PropagationService, MetaLearningService)
✅ Application Layer: 36 tests (ToolExecutionHandler, MCP tool dispatch, AgentTask coordination)
✅ Infrastructure Layer: 53 tests (D1Repository, VectorizeRepository, CloudflareAIProvider, D1TaskRepository)
✅ Presentation Layer: 12 tests (MCPRouter, CORS, error handling)
✅ Domain Models: 18 tests (AgentTask entity)

Test Structure

Tests are co-located with source files using the .test.ts suffix:

src/
├── domain/
│   ├── models/
│   │   ├── ContextSnapshot.ts
│   │   └── ContextSnapshot.test.ts
│   └── services/
│       ├── ContextService.ts
│       ├── ContextService.test.ts
│       ├── CausalityService.ts
│       ├── CausalityService.test.ts
│       ├── MemoryManagerService.ts
│       ├── MemoryManagerService.test.ts
│       ├── PropagationService.ts
│       ├── PropagationService.test.ts
│       ├── MetaLearningService.ts
│       └── MetaLearningService.test.ts
├── application/
│   └── handlers/
│       ├── ToolExecutionHandler.ts
│       └── ToolExecutionHandler.test.ts
└── ...

All tests use Vitest with mocking for external dependencies (D1, AI services).

Continuous Integration

This project uses GitHub Actions for automated testing and quality checks.

Automated Checks on Every Push/PR:

✅ TypeScript compilation (npm run type-check)
✅ Unit tests (npm test)
✅ Test coverage reports
✅ Code formatting (Biome)
✅ Linting (Biome)

Status Badges:

CI status displayed at top of README
Automatically updates on each commit
Shows passing/failing state

Workflow Configuration: .github/workflows/ci.yml

The CI pipeline runs on Node.js 20.x and ensures code quality before merging.

Database Setup

This project uses Cloudflare D1 for persistent context storage.

Initial Setup

Create D1 Database:
```
wrangler d1 create mcp-context
```

Update wrangler.jsonc with your database ID:

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "mcp-context",
      "database_id": "your-database-id-here"
    }
  ]
}

Run Initial Migration:

wrangler d1 execute mcp-context --file=./migrations/0001_initial_schema.sql

Local Development

For local testing, initialize the local D1 database:

wrangler d1 execute mcp-context --local --file=./migrations/0001_initial_schema.sql

Verify Schema

Check that tables were created successfully:

# Production
wrangler d1 execute mcp-context --command="SELECT name FROM sqlite_master WHERE type='table'"

# Local
wrangler d1 execute mcp-context --local --command="SELECT name FROM sqlite_master WHERE type='table'"

Database Migrations

All database schema changes are managed through versioned migration files in migrations/:

0001_initial_schema.sql - Initial context snapshots table with semantic indexes

See migrations/README.md for detailed migration management guide.

License

This project is licensed under the MIT License - see the LICENSE file for details.

🔬 Research Foundation

This implementation is based on the research paper "Semantic Intent as Single Source of Truth: Immutable Governance for AI-Assisted Development".

Core Principles Applied:

Semantic Over Structural - Use meaning, not technical characteristics
Intent Preservation - Maintain semantic contracts through transformations
Observable Anchoring - Base behavior on directly observable properties
Immutable Governance - Protect semantic integrity at runtime

Related Resources:

🤝 Contributing

We welcome contributions! This is a reference implementation, so contributions should maintain semantic intent principles.

How to Contribute

Read the guidelines: CONTRIBUTING.md
Check existing issues: Avoid duplicates
Follow the architecture: Maintain layer boundaries
Add tests: All changes need test coverage
Document intent: Explain WHY, not just WHAT

Contribution Standards

✅ Follow semantic intent patterns
✅ Maintain hexagonal architecture
✅ Add comprehensive tests
✅ Include semantic documentation
✅ Pass all CI checks

Quick Links:

Contributing Guide - Detailed guidelines
Code of Conduct - Community standards
Architecture Guide - Design principles
Security Policy - Report vulnerabilities

Community

💬 Discussions - Ask questions
🐛 Issues - Report bugs
🔒 Security - Report vulnerabilities privately

🔒 Security

Security is a top priority. Please review our Security Policy for:

Secrets management best practices
What to commit / what to exclude
Reporting security vulnerabilities
Security checklist for deployment

Found a vulnerability? Email: [email protected]

添加此服务器

用我们的密钥与日志托管一份副本。

Server facts

About Semantic Wake Intelligence

Tools

Questions

How do I install Semantic Wake Intelligence?

Does Semantic Wake Intelligence need an API key?

What transport does Semantic Wake Intelligence use?

When was Semantic Wake Intelligence last checked?

Documentation

Wake Intelligence MCP

What's New in v3.7.0

Previous: v3.6.0

Previous: v3.5.0

📚 Table of Contents

🧠 Wake Intelligence Brain Architecture

Layer 1: Causality Engine (Past - WHY)

Layer 2: Memory Manager (Present - HOW)

Layer 3: Propagation Engine (Future - WHAT)

Layer 4: Meta-Learning Engine (Adaptive - HOW WELL)

Layer 5: Personality Modes (Presentation - HOW SURFACED)

Temporal Intelligence Flow:

🎯 What Makes This Different

🚀 Quick Start

Prerequisites

Installation

Deploy to Production

📚 Learning from This Implementation

Architecture Files:

Documentation & Patterns:

Connect to Cloudflare AI Playground

Connect Claude Desktop to your MCP server

🏗️ Architecture

Layer Responsibilities:

Benefits:

Features

Core Context Management

Wake Intelligence Layer 1: Causality (Past)

Wake Intelligence Layer 2: Memory (Present)

Wake Intelligence Layer 3: Propagation (Future)

Wake Intelligence Layer 4: Meta-Learning (Adaptive)

Wake Intelligence Layer 5: Personality Modes (Presentation)

Wake Intelligence v3.5.0: Observability + Rune Integration

Agent Task Coordination (v3.7.0)

🧪 Testing

Run Tests

Test Coverage

Test Structure

Continuous Integration

Database Setup

Initial Setup

Local Development

Verify Schema

Database Migrations

License

🔬 Research Foundation

Core Principles Applied:

Related Resources:

🤝 Contributing

How to Contribute

Contribution Standards

Community

🔒 Security