ContextStream MCP Server

Persistent memory + semantic search + dependency/impact analysis for Cursor, Claude Code, Windsurf, VS Code, Codex CLI, and any MCP client.

⭐ If this saves you time, please star the repo — it helps others find it!

_{Your AI remembers decisions, preferences, and context — across sessions and tools.}

The Real Cost of AI Amnesia

Every developer using AI tools has felt this frustration:

Monday morning. You've spent 3 hours with Claude explaining your authentication architecture, the edge cases, why you chose JWT over sessions, the rate limiting strategy. The AI finally gets it. You ship great code together.

Monday afternoon. New chat window. The AI has no idea what JWT is in your context. It suggests sessions. You explain everything again.

Tuesday. You switch to Cursor for a quick refactor. Start from zero. "We use TypeScript with strict mode." "Our API follows REST conventions." "The user service is in /src/services." Again.

A week later. "Why did we build it this way?" Nobody remembers. The decision rationale is buried in a closed Slack thread. The AI certainly doesn't know.

A month later. New team member joins. Days of onboarding conversations. Explaining the same architectural decisions. Documenting tribal knowledge that should already exist.

This isn't a minor inconvenience. It's death by a thousand cuts.

Every re-explanation is lost productivity. Every forgotten decision is technical debt. Every context switch is cognitive load. Every new teammate is weeks of redundant knowledge transfer.

Your AI is brilliant for 30 minutes at a time—then it's a goldfish.

What If Your AI Actually Learned?

ContextStream gives your AI a permanent brain.

You: "Initialize session. Remember: we use PostgreSQL, TypeScript strict mode,
     and JWT for auth. Rate limits are 100 req/min per user."

...3 weeks later, different tool, new conversation...

You: "What database do we use?"
AI: "You're using PostgreSQL. You also prefer TypeScript with strict mode
     and JWT authentication with 100 req/min rate limiting per user."

It remembers. Across sessions. Across tools. Forever.

Not just facts—decisions, context, and reasoning:

You: "Why did we choose PostgreSQL over MongoDB?"
AI: "Based on your captured decision from March 15th: 'Chose PostgreSQL for
     ACID compliance and complex joins in the reporting module. MongoDB
     considered but rejected due to transaction requirements.'"

🚀 2-Minute Setup

1. Get Your API Key

Sign up at contextstream.io → Settings → API Keys → Create

2. Add to Your MCP Config

Claude Code / Cursor / Windsurf / VS Code:

{
  "mcpServers": {
    "contextstream": {
      "command": "npx",
      "args": ["-y", "@contextstream/mcp-server"],
      "env": {
        "CONTEXTSTREAM_API_URL": "https://api.contextstream.io",
        "CONTEXTSTREAM_API_KEY": "your_api_key"
      }
    }
  }
}

Codex CLI (~/.codex/config.toml):

[mcp_servers.contextstream]
command = "npx"
args = ["-y", "@contextstream/mcp-server"]

[mcp_servers.contextstream.env]
CONTEXTSTREAM_API_URL = "https://api.contextstream.io"
CONTEXTSTREAM_API_KEY = "your_api_key"

Codex expects snake_case mcp_servers keys. After editing, fully restart Codex.

AI Rules Files (Recommended)

Adding rules files ensures your AI automatically uses ContextStream for memory on every conversation.

⚠️ Critical: Tool Naming Convention

AI Tool	Tool Name Format	Example
Claude Code	mcp__<server>__<tool>	mcp__contextstream__session_init
All Others (Codex, Cursor, Windsurf, Cline, etc.)	<tool> (raw)	session_init

For Claude Code — Create CLAUDE.md in your project root:

## ContextStream Integration

| Message | What to Call |
|---------|--------------|
| **1st message** | `mcp__contextstream__session_init(folder_path="...", context_hint="<user's message>")` |
| **2nd+ messages** | `mcp__contextstream__context_smart(user_message="<user's message>")` |
| **After tasks** | `mcp__contextstream__session_capture(...)` |

**NO EXCEPTIONS.** Call these tools before responding.

For Codex CLI — Create AGENTS.md in ~/.codex/ (global) or project root:

## ContextStream Integration

| Message | What to Call |
|---------|--------------|
| **1st message** | `session_init(folder_path="...", context_hint="<user's message>")` |
| **2nd+ messages** | `context_smart(user_message="<user's message>")` |
| **After tasks** | `session_capture(...)` |

**NO EXCEPTIONS.** Call these tools before responding.

For other editors — See full templates in the docs.

3. Experience Memory

You: "Initialize session and remember I prefer functional React components"

Open a new conversation (even in a different tool):

You: "What's my React preference?"
AI: "You prefer functional React components."

✨ That's it. Your AI remembers now.

Beyond Memory: Intelligence That Compounds

Memory is just the foundation. ContextStream understands your codebase at a deeper level.

🔴 Lessons Learned — Never Repeat Mistakes

When your AI makes a mistake—wrong approach, broken build, production issue—capture it as a lesson:

You: "Capture lesson: Always run tests before pushing to main"

These lessons surface automatically in future sessions. Before the AI takes a similar action, it sees the warning. Your AI learns from mistakes just like you do.

Lessons are categorized by severity (critical, high, medium, low) and automatically retrieved when relevant context is detected.

📊 Impact Analysis

You: "What breaks if I change the UserService class?"

See all dependencies and side effects before you refactor. No more surprise breakages.

🔍 Semantic Code Search

You: "Find where we handle authentication errors"

Search by meaning, not keywords. Find code by what it does, not what it's named.

🧬 Knowledge Graph

Decisions, code, and documentation—all connected. Ask "why" and get answers with full context.

🤖 Auto-Context Loading

Context loads automatically on first interaction. No manual setup:

═══════════════════════════════════════════
🧠 AUTO-CONTEXT LOADED (ContextStream)
═══════════════════════════════════════════
📁 Workspace: acme-corp
📂 Project: backend-api

📋 Recent Decisions:
   • Use PostgreSQL for persistence
   • JWT for authentication

⚠️ Active Lessons:
   • Always run tests before pushing

🧠 Recent Context:
   • [decision] API rate limiting strategy
   • [preference] TypeScript strict mode
═══════════════════════════════════════════

71 MCP Tools

Session & Memory

Code Intelligence

AI Integration

View all 71 tools →

Why Not Built-in Memory?

Privacy & Security

• 🔐 Encrypted at rest — AES-256 encryption for all stored data
• 🚫 Never trains on your data — Your code is yours. Period.
• 🎛️ You control access — Workspace permissions, API key management
• 🗑️ Delete anytime — Full data deletion on request

Works Everywhere

ContextStream uses the Model Context Protocol—the emerging standard for AI tool integrations.

Supported today:

• Claude Code
• Cursor
• Windsurf
• VS Code (with MCP extension)
• Codex CLI
• Cline
• Kilo Code
• Roo Code
• Any MCP-compatible client

One integration. Every tool. Same memory.

Quick Reference

Environment Variables

Essential Commands

# Install globally
npm install -g @contextstream/mcp-server

# Or run via npx (recommended for MCP configs)
npx @contextstream/mcp-server

First Session Checklist

1. ✅ Add MCP config to your editor
2. ✅ Start a conversation: "Initialize session for [project-name]"
3. ✅ Tell it your preferences: "Remember we use TypeScript strict mode"
4. ✅ Make a decision: "Capture decision: Using PostgreSQL for the user database"
5. ✅ Open a new conversation and ask: "What are my preferences?"

Links

Contributing

We welcome contributions:

1. Report bugs — Open an issue
2. Request features — Share ideas in GitHub Issues
3. Submit PRs — Fork, branch, and submit

Development

git clone https://github.com/contextstream/mcp-server.git
cd mcp-server
npm install
npm run dev      # Development mode
npm run build    # Production build
npm run typecheck

License

MIT