I’ve been using Claude Code heavily for infrastructure work across multiple environments – homelab, production, various projects. The problem I kept running into: context loss between sessions.
You know the drill. You’re deep into debugging something, have Claude fully up to speed on the architecture, the constraints, the decisions you’ve made. Then you close the terminal. Next day, fresh Claude session, and you’re back to explaining everything from scratch.
The Foundation: Intent Layers and Filesystem-First
Before diving into contexts-mcp, I want to be clear about what I’m building on top of. The foundation matters.
Intent Layers – hierarchical CLAUDE.md and AGENTS.md files throughout your codebase – are essential. They capture the spatial context: what this directory does, the constraints, the patterns, the pitfalls. When Claude enters a directory, it loads the relevant intent node and understands the boundaries.
Vercel’s recent piece on building agents with filesystems and bash reinforces this: use grep, cat, find. Let agents explore hierarchical data with tools they already understand. No custom MCP servers needed for basic context retrieval.
I use all of this. My repos have intent files. My ~/.claude/CLAUDE.md defines my working style, shortcuts, and constraints. Per-environment bootstrap files at ~/.claude/env/homelab.md capture network topology and access patterns. Inferal’s approach of version-controlled workspace knowledge is exactly right.
This works. For 80% of my work, intent layers and filesystem context are enough.
The Gap: Temporal Context
But there’s a gap these approaches don’t address: temporal context.
Intent layers tell Claude where it is and what the rules are. They don’t tell it what we were doing yesterday or where we left off two weeks ago.
I could keep a session file:
~/.claude/sessions/homelab/2026-01-24-jwt-migration.mdAnd grep through them. That works for a while. But:
- Semantic search beats keywords – “find sessions about auth” should match “JWT validation issue” even if I never typed “auth”
- Scale matters – 100+ sessions and grep returns noise
- Cross-environment queries – “when did I last deal with SSL certs anywhere?”
- Structured retrieval – I want task/context/blockers/next_steps as queryable fields, not free-form markdown
Environment Isolation: Not Just Context, But Tools
Here’s something that doesn’t get enough attention: MCP tool isolation per environment.
When you’re working across environments, you don’t just need different context – you need different capabilities. My homelab environment has access to proxmox-mcp, unifi-mcp, and truenas-mcp. My production environment has kubernetes-mcp and postgres-mcp. My writing environment might only have obsidian-mcp.
With contexts-mcp, each environment routes to its own MCP relay:
environments:
homelab:
url: http://homelab-relay:8000
# Tools: proxmox, unifi, truenas, pihole
prod:
url: https://prod-relay.internal:8000
# Tools: kubernetes, postgres, datadog
writing:
url: http://localhost:8001
# Tools: obsidian, wordpressThis isn’t just organization – it’s security and cognitive load reduction. When Claude is working in my writing environment, it literally cannot see or invoke production database tools. Not through permissions, but through architecture. The MCP relay for that environment simply doesn’t expose them.
And when I switch environments with load prod, Claude’s entire toolset changes. Different capabilities, different context, different guardrails. The environment isn’t just metadata – it’s a complete operational boundary.
The Solution: contexts-mcp
So I built contexts-mcp – a session state manager that adds temporal context and environment-scoped tooling on top of the intent layer foundation.
The workflow is simple:
# Start of day - restore where you left off
rs homelab
# Claude now knows:
# - Task: Migrating auth to JWT
# - Context: Created middleware, updated user model
# - Next steps: Add refresh tokens, write tests
# - Tools: proxmox, unifi, truenas (homelab MCP relay)
# ... work on it ...
# End of session
ss
# Session saved to Qdrant with full contextDays later, can’t remember where you left off with that database thing?
rs homelab "postgres migration"
# Returns semantically similar sessions, not just keyword matchesHow It Works
Session Storage
When you save a session (ss), it captures:
- task – what you’re working on
- context – relevant details, decisions made, files touched
- blockers – what’s stuck (optional)
- next_steps – what needs to happen next
This gets embedded using sentence-transformers/all-MiniLM-L6-v2 and stored in Qdrant. Semantic search means “auth bug” finds sessions about “JWT token validation issue” even if those exact words weren’t used.
Environment Routing
Each environment in the config points to an MCP relay with its own toolset:
environments:
homelab:
url: http://relay-mcp:8000
description: Personal infrastructure
context:
networks:
allowed: [192.168.50.0/24]
omega: false
prod:
url: https://mcp.prod.example.com
description: Production - be careful
context:
omega: true # Triggers extra cautionThe omega flag is something I added after nearly running a destructive command against production data. When true, Claude gets reminded to be extra careful. Belt and suspenders.
Token-Based Concurrency
Each rs <env> creates a session token. This means you can have:
- Terminal 1: Claude working on homelab (with homelab tools)
- Terminal 2: Claude working on prod (with prod tools)
No cross-contamination. Each session routes to its own MCP relay, maintains separate context, and sees only the tools registered for that environment.
Architecture
┌─────────────────────────────────────────────────────────────┐
│ Claude Code │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ contexts-mcp │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ /ss │ │ /rs │ │ /mcp/sse proxy │ │
│ │ /sessions │ │ /bootstrap│ │ /mcp/messages │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌───────────────────────────┐ ┌────────────────────────────┐
│ Qdrant │ │ relay-mcp (per env) │
│ - session-memory │ │ homelab: proxmox, │
│ - global-context │ │ unifi, truenas │
└───────────────────────────┘ │ prod: k8s, postgres │
│ writing: obsidian │
└────────────────────────────┘contexts-mcp sits between Claude and your MCP servers. It handles:
- Session save/restore with Qdrant
- Environment routing with tool isolation
- MCP protocol translation to downstream relays
When You Need This (And When You Don’t)
You probably don’t need contexts-mcp if:
- You work on one project at a time
- Your sessions are short and self-contained
- Grep through markdown session files works fine
- You use the same MCP tools everywhere
You might need it if:
- You work across multiple environments (dev/staging/prod, or multiple projects)
- You want different MCP tools available per environment
- You have long-running tasks that span days or weeks
- You want “where was I?” to be a semantic search, not a keyword hunt
- You need concurrent Claude sessions with isolated contexts and toolsets
Related Work
This space is evolving quickly, and there are other approaches worth knowing about:
- claude-code-vector-memory – Session summaries stored in ChromaDB. Similar semantic search idea, focused on single-project memory with git-aware indexing.
- Context Continuation MCP – Token limit management with intelligent context continuation. Solves a different but related problem: what happens when you hit the context window limit.
- claude-code-memory – Interesting approach focused on code patterns and decisions rather than session state. Captures why code is the way it is.
- Mem0 – More general-purpose AI memory layer. If you need memory across multiple AI tools, not just Claude Code, worth investigating.
What contexts-mcp adds that I haven’t seen elsewhere: per-environment MCP tool isolation. Most solutions focus on context/memory. This also gives you environment-scoped capabilities.
A Note on Claude Code’s Native Tool Search
Claude Code 2.1.7+ introduced native tool search that kicks in when MCP tool descriptions exceed 10% of the context window. This lazy-loads tools on demand rather than stuffing all descriptions into context upfront.
This is great, but it solves a different problem. Native tool search is about token efficiency – don’t load all 100 tool descriptions when Claude only needs 5 right now.
contexts-mcp is about operational boundaries – which tools exist at all for a given environment. When I’m in my writing environment, production database tools don’t just get lazy-loaded on demand – they literally don’t exist. The relay-mcp for that environment doesn’t expose them.
These are orthogonal concerns: – Tool search helps when you have many tools and want efficient context usage – Environment isolation helps when you need security boundaries and cognitive load reduction
You can (and probably should) use both.
Future Directions
Ideas I’m considering, some borrowed from the projects above:
- Hybrid scoring – Combine semantic similarity with recency weighting. Recent sessions about “auth” might matter more than old ones.
- Token monitoring – Track context window usage and auto-suggest session saves before hitting limits.
- Code pattern memory – Capture architectural decisions alongside session state, à la gajakannan’s approach.
- Automatic session capture – Detect “natural break points” and suggest saves, rather than relying on manual
ss. - Session summaries – Generate condensed versions of long sessions for faster context loading.
Try It
Both projects are MIT licensed:
- contexts-mcp – session memory + environment routing
- relay-mcp – MCP aggregation with auth support
Start with intent layers and filesystem context. When your session history outgrows grep, or when you need isolated toolsets per environment, add contexts-mcp on top.
