Eywa Continuum
Cross-session memory for Claude Code β MCP server for context handoffs
Ask AI about Eywa Continuum
Powered by Claude Β· Grounded in docs
I know everything about Eywa Continuum. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Eywa MCP
Cross-session memory for Claude Code (MCP server + CLI).
The Problem
Claude Code sessions are ephemeral. Context is lost between sessions, so you start fresh each time and re-explain what you were working on.
For heavy Claude Code users with hundreds of sessions, that context reset becomes a major productivity drain.
The Solution
Eywa extracts a structured handoff at the end of each session and retrieves relevant past context at the start of the next one.
The name comes from the neural network in Avatar: Eywa connects sessions the way Eywa connects living memory.
How It Works
Eywa runs a deterministic pipeline around your Claude Code transcripts:
- Session Detection: 4-strategy fallback (explicit session ID, PID tracing, CWD mtime, global mtime).
- Session Conversion: JSONL transcript -> normalized markdown conversation.
- Extraction: LLM-powered structured handoff extraction.
- Indexing: Inverted index with metadata + TF-IDF-friendly keyword/project maps.
- Retrieval: Query keyword scoring + recency decay to return relevant handoffs.
Claude Code JSONL Session
|
v
[Session Detection]
|
v
[JSONL -> Markdown]
|
v
[Structured Extraction]
|
v
[Handoff Markdown + Index]
|
v
eywa_get()
Two-Stage Setup
Stage 1: Batch Index (one-time setup)
Use eywa-batch to process existing historical sessions in bulk through OpenRouter.
-
You can pick any OpenRouter model (Gemini Flash, Claude, GPT, Llama, etc.)
-
Default batch model:
google/gemini-3-flash-preview -
Designed for hundreds of prior sessions
-
Fast + low-cost extraction pass
-
Builds your initial handoff corpus and index
Stage 2: Runtime
Run eywa-mcp alongside Claude Code for ongoing sessions.
- Uses Claude (Sonnet) extraction at session end (
eywa_extract()) - Retrieves relevant context at session start (
eywa_get()) - Installs a companion CLI (
eywa) for scripts and manual use
Installation
Prerequisites
- Python 3.10+
- Node.js 18+
- Claude Code
Option A: Bootstrap (recommended)
Run the repo bootstrap script to check prerequisites and install both Python and Node dependencies:
./setup.sh
This installs three commands:
eywa-mcp(MCP stdio server)eywa(CLI: get/extract/rebuild-index)eywa-batch(OpenRouter-powered batch indexing)
Option B: Manual install
1) Install Python package (editable)
pip install -e .
2) Install Node extractor dependencies
cd eywa/extractors
npm install
cd ../..
3) Configure environment
cp .env.example .env
4) Register MCP server
Add to claude_desktop_config.json or ~/.claude.json:
{
"mcpServers": {
"eywa": {
"command": "eywa-mcp"
}
}
}
5) Run manually (optional)
eywa-mcp
Configuration
| Variable | Default | Description |
|---|---|---|
EYWA_DATA_DIR | ~/.eywa | Runtime storage root for handoffs and index |
EYWA_SESSIONS_DIR | ~/.claude/projects | Claude Code session JSONL root |
EYWA_TASKS_DIR | <EYWA_SESSIONS_DIR parent>/tasks | Tasks directory used for PID-based session detection |
EYWA_CLAUDE_MODEL | sonnet | Model used by runtime extraction (eywa_extract) |
EYWA_OPENROUTER_MODEL | google/gemini-3-flash-preview | OpenRouter model used by batch indexing (eywa-batch) |
OPENROUTER_API_KEY | (unset) | OpenRouter API key for batch extraction |
EYWA_BATCH_DELAY | 0.5 | Delay (seconds) between batch API calls |
EYWA_BATCH_CONCURRENCY | 5 | Concurrent sessions processed by eywa-batch |
EYWA_TIMEZONE | UTC | Timezone for rendered session timestamps |
EYWA_LOG_LEVEL | INFO | Logging verbosity |
Usage
Eywa exposes two MCP tools (for Claude Code) and a CLI (for humans/scripts).
eywa_get()
Retrieve relevant context from prior handoffs.
No query (recent sessions):
{"max_handoffs": 3}
With query:
{"query": "mcp tool routing and index scoring", "days_back": 30, "max_handoffs": 4}
With tighter options:
{"query": "release pipeline", "days_back": 7, "max_handoffs": 2}
Sample output:
## Eywa: 2 past sessions
# Implemented MCP routing fallback logic
## What Happened
- Added explicit tool dispatch guard for unknown tool names.
- Introduced parse-time validation for input payload constraints.
## Open Threads
- Add integration tests for malformed tool inputs.
eywa_extract()
Extract and persist a handoff from the active session.
Auto-detect active session:
{}
Explicit session ID:
{"session_id": "12345678-1234-1234-1234-123456789abc"}
CLI (eywa)
Manual equivalents of the MCP tools:
eywa get # 3 most recent sessions
eywa get "mcp tool routing" --days-back 30 --max 5
eywa extract # auto-detect current session
eywa extract 1b2f6f6b # 8-char short ID
eywa extract 1b2f6f6b-65a6-... # full UUID
eywa rebuild-index # rebuild index from stored handoffs
Batch Indexing
Run one-time bulk import of historical sessions:
eywa-batch
Set your OpenRouter API key first:
export OPENROUTER_API_KEY=...
Choose a model (optional):
export EYWA_OPENROUTER_MODEL=anthropic/claude-3.5-sonnet
Dry run (no API calls):
eywa-batch --dry-run
Custom delay between calls:
eywa-batch --delay 1.0
Set concurrency (1-20):
eywa-batch --concurrency 10
Limit the run:
eywa-batch --max 50
Force reindex all sessions:
eywa-batch --reindex
What to expect:
- Scans
EYWA_SESSIONS_DIRfor*.jsonl - Skips already-indexed sessions (unless
--reindex) - Skips very short/trivial sessions
- Uses OpenRouter Chat Completions with your selected model
- Writes handoffs to
YYYY/MM/DD/<session_id>.md - Updates
handoff-index.jsonincrementally - Prints progress and end-of-run summary
License
MIT. See LICENSE.
