Your AI forgot
what you already built.

Rainman is a persistent memory layer for AI coding tools. Set up once, remember forever. It learns your codebase — patterns, failures, solutions, decisions — and surfaces them exactly when needed. Across every session.

Zero LLM calls Runs locally Zero dependencies 124 tests, <1s
Origin Story

Born from a $0 bug that
cost hours of debugging

We were debugging a systematic voting bias in an election predictor. The AI assistant declared the problem "unfixable by prompt engineering" and spent hours exploring workarounds.


The fix already existed in the codebase. A 516-line, science-grounded module that assigns political identity using ANES/Pew research data — zero LLM calls. Built weeks earlier. The AI had full codebase access, 500+ lines of CLAUDE.md, memory files. It still forgot.


Static docs describe what things are. They don't activate when needed. That's the gap Rainman fills.

The Problem

AI declared "unfixable"

Election predictor showed 15-20pp anti-incumbent bias. Claude Code couldn't find the existing fix.

The Discovery

516 lines, forgotten

political_identity.py — science-grounded, zero-LLM — was already built. Never surfaced.

The Insight

Static docs don't activate

CLAUDE.md describes what exists. It doesn't fire when the AI needs it. No contextual retrieval.

The Solution

Rainman

Persistent memory with scoring-based retrieval. Plugs into Claude Code via MCP + hooks.

Validated

The forgotten module now
surfaces as result #1

Tested on the same codebase where the problem was discovered. 307 memories ingested from git history, file structure, and manual learnings.

> rainman recall "election voting bias"
political_identity.py — the exact module that was "forgotten"
0.937
> rainman recall "political identity assignment"
RLHF bias failure + political_identity.py reference
0.970
> rainman recall "CEP migrate claude sonnet"
CEP calibration warning — DO NOT migrate without re-validation
0.891
> rainman recall "cognitrait personality memory"
CogniTrait description + related engine files
0.867
Scoring Engine

Four signals, zero LLM

Every memory gets a composite score from four components. No embeddings, no API calls — keyword matching, math, and cognitive science.

Keyword Match

Overlap between query and memory content, tags, and file references. Rehearsal boost for frequently accessed memories.

0.35

Temporal Decay

ACT-R power-law decay with 14-day half-life. Recently accessed memories stay fresh. Old unused memories fade.

0.25

Importance

Failures score 0.9, solutions 0.8, decisions 0.7. Extra boost for keywords like "critical", "bug", "fix".

0.20

Associative

Memories auto-link by keyword overlap. Recalling one boosts its neighbors. Two-phase retrieval surfaces the graph.

0.20
Integration

MCP + Hooks. Plug and play.

MCP Server

5 tools for Claude Code

recall, remember, context, links, status. Claude searches your memory before declaring anything unsolvable.

claude mcp add rainman -- python -m rainman serve
CLI

Full command line

init, add, recall, status, links, context, ingest, export, serve. Works standalone or alongside MCP.

rainman ingest --git --files rainman recall "auth pattern" rainman add "JWT expires in 30d" -c pattern

PostCompact: The Killer Feature

When Claude's context gets compacted during long sessions, memories disappear. Rainman's PostCompact hook fires at exactly that moment — it reads the compaction summary, recalls relevant knowledge, and re-injects it into Claude's fresh context. The one moment everything gets lost is the one moment Rainman activates.

SessionStart Hook

Context from day one

Every new session starts with your project's top memories loaded. Claude knows what exists before you ask.

PostToolUse Hook

Auto-learn silently

When Claude reads a file, edits code, or runs tests — Rainman records it. No manual input. Knowledge accumulates.

Architecture

Stdlib only. Nothing to install.

rainman/ core/ models.py # Memory + RecallResult dataclasses scoring.py # Keyword, decay, importance, associative sentiment.py # Keyword-based classifier (zero LLM) engine.py # add, recall, context, links, forget store.py # Layered JSON (global + project) mcp/ server.py # MCP stdio server (JSON-RPC 2.0) hooks/ session_start # Load context at session start post_compact # Re-inject after compaction post_tool_use # Auto-learn from tool usage ingest/ git.py # Parse git log into memories files.py # Scan project tree 124 tests · 0 dependencies · <1s test suite
Getting Started

30 seconds. Three commands.

1

Install

Pure Python, zero dependencies. Works on any OS with Python 3.10+.

$ pip install git+https://github.com/yan-yanko/rainman.git
2

Setup

One command configures everything — initializes storage, registers the MCP server with Claude Code, installs all three hooks, and creates your project config.

$ rainman setup ✓ Initialized .rainman/ in current directory ✓ Registered MCP server with Claude Code ✓ Configured 3 Claude Code hooks ✓ Created .mcp.json for project
3

Verify

Self-test confirms engine, persistence, hooks, and MCP integration are all working.

$ rainman doctor ✓ Engine: add + recall round-trip ✓ Engine: scoring produces ranked results ✓ Persistence: save and reload from disk ✓ Project: .rainman/ directory exists ✓ MCP: server module importable ✓ Hooks: all 3 hook files present 14 passed, 0 failed

Set up once. Remember forever.

No re-activation between sessions. No manual input. Rainman's hooks fire automatically every time a session starts, every time context compacts, every time a tool runs. Memories persist on disk and grow with every session. rainman recall "your query"

Platform Support

Works with your editor.

Claude Code
Full integration — hooks + MCP
Cursor
MCP server + rules file
Windsurf
MCP server
Continue.dev
MCP server
Copilot
MCP server
Any MCP Client
JSON-RPC 2.0 stdio

The core engine and MCP server work with any MCP-compatible client. Claude Code gets the deepest integration with automatic hooks for session start, context compaction, and tool usage. CLI works standalone everywhere.

Stop losing what you've already built.

pip install git+https://github.com/yan-yanko/rainman.git && rainman setup

View on GitHub Back to top