Eywa

Cross-session memory for Claude Code (MCP server + CLI).

Build PyPI License

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:

1. Session Detection: 4-strategy fallback (explicit session ID, PID tracing, CWD mtime, global mtime).
2. Session Conversion: JSONL transcript -> normalized markdown conversation.
3. Extraction: LLM-powered structured handoff extraction.
4. Indexing: Inverted index with metadata + TF-IDF-friendly keyword/project maps.
5. 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_DIR for *.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.json incrementally
• Prints progress and end-of-run summary

License

MIT. See LICENSE.