RAWThink

Your AI assistant forgets everything between sessions. RAWThink fixes that.

Persistent memory for Claude Code — hybrid search, knowledge graph, session lifecycle. Think of it as a second brain that grows with every conversation.

The Problem

Claude Code is stateless. Every session starts from zero. You explain the same context, re-establish the same decisions, re-discover the same insights. Yesterday's breakthrough is today's cold start.

RAWThink gives your AI a memory that persists, decays naturally, and revises itself when you change your mind. It's a 15-tool MCP server that turns Claude Code into a long-term thinking partner.

Article

Read the full story: Your AI Doesn't Remember You

Quick Start

Prerequisites

• Python 3.10+

• Docker (for Qdrant vector database)

• Ollama (for local embeddings)

• Node.js (for the SessionStart hook)

Install & set up

pip install rawthink-mcp
rawthink-install              # creates project dir with vault, configs, and starter files
cd ~/rawthink-vault           # go to your project directory
docker compose up -d          # start Qdrant (docker-compose.yml is here)
ollama pull bge-m3            # download embedding model

Restart Claude Code. Done.

rawthink-install creates a self-contained project directory at ~/rawthink-vault with vault structure, CLAUDE.md, THINKING_DIRECTIVES.md, SETUP.md, docker-compose.yml, and /rtclose command. Run rawthink-install --vault ~/my-vault to customize the location.

Add to your ~/.claude.json:

{
  "mcpServers": {
    "rawthink": {
      "command": "rawthink-mcp",
      "env": {
        "RAWTHINK_VAULT": "/path/to/your/vault"
      }
    }
  }
}

Create vault structure:

mkdir -p vault/{sessions,qnotes,archive/raw,outputs}

Install from source instead of PyPI:

git clone https://github.com/ygtalp/rawthink-mcp.git
cd rawthink-mcp
pip install -e .

Your First Session

Your vault starts empty — that's the point. Open Claude Code and start talking:

You:   "We're building a REST API. Let's use PostgreSQL with connection pooling."
Claude: [responds with technical discussion]

You:   "/qnote we decided on PostgreSQL + pgBouncer for the API layer"
       → saved to your vault as a searchable quick note

You:   "/rtclose"
       → Session exported, entities extracted, handoff written

Next session, Claude loads the handoff automatically and picks up where you left off. After a few sessions, your vault looks like this:

> search_thoughts("how did we handle the database?")

1. [2025-03-15_002] API Architecture Decisions        score: 0.74
   Decided on PostgreSQL + pgBouncer for connection pooling.
   Key insight: pool_mode=transaction for serverless...

2. [2025-03-22_001] Performance Review                 score: 0.61
   Revisited DB strategy — added read replicas for
   reporting queries, write primary stays single-node...

> read_graph(summary=True)

Knowledge Graph: 42 entities, 38 relations

  decision (5)
  - postgres-connection-pooling (3 obs) act=0.97
  - api-versioning-strategy    (4 obs) act=0.85
  - auth-jwt-vs-session        (2 obs) act=0.72
  concept (8)
  - cqrs-pattern               (3 obs) act=0.91
  - event-sourcing             (5 obs) act=0.88
  ...

What It Does

Three-layer memory

1. Hot cache (MEMORY.md) — loaded every session, essential context

2. Knowledge graph (JSONL) — entities, relations, temporal observations with belief revision

3. Semantic search (Qdrant) — hybrid dense + BM25 across all sessions and qnotes

Session lifecycle

Session start (handoff loads) → Think together → /rtclose →
JSONL export + entity extraction + handoff for next session

Key capabilities

• Hybrid search: BGE-M3 dense embeddings + BM25 sparse vectors, fused with RRF

• Belief revision: observations can be invalidated, superseded, and tracked over time

• Activation decay: unused knowledge fades (~23-day half-life), accessed knowledge stays hot

• Epistemic typing: mark entities as assertion, hypothesis, or speculation

• Multi-terminal safe: parallel sessions don't overwrite each other's handoffs

• Thinking directives: structured discipline for human-AI thinking partnerships

• Ollama fallback: embedding cache for when Ollama is temporarily unavailable

Architecture

┌─────────────────────────────────────────────────┐
│                  Claude Code                    │
│              (MCP Client)                       │
└──────────────────┬──────────────────────────────┘
                   │ MCP (stdio)
┌──────────────────▼──────────────────────────────┐
│                rawthink                         │
│           (FastMCP Server)                      │
│                                                 │
│  ┌─────────────┐  ┌──────────┐  ┌────────────┐  │
│  │   Indexer   │  │  Graph   │  │  Chunker   │  │
│  │ (Qdrant +   │  │ (JSONL   │  │ (Markdown  │  │
│  │  Ollama)    │  │  KG)     │  │  splitter) │  │
│  └──────┬──────┘  └────┬─────┘  └────────────┘  │
│         │              │                        │
│  ┌──────▼──────┐  ┌────▼─────┐                  │
│  │   Qdrant    │  │ memory   │                  │
│  │  (Docker)   │  │ .jsonl   │                  │
│  └─────────────┘  └──────────┘                  │
└─────────────────────────────────────────────────┘
                   │
        ┌──────────▼──────────┐
        │       Vault         │
        │  sessions/ qnotes/  │
        │  archive/  outputs/ │
        └─────────────────────┘

MCP Tools

Search (5 tools)

Knowledge Graph (10 tools)

How It's Different

RAWThink is not a codebase analyzer or a simple key-value memory. It's a living knowledge system designed for thinking partnerships.

Why JSONL?

Human-readable, git-diffable, zero dependency. At 120 entities the graph loads in <50ms. At 10K entities ~1.4s. The optimization path is clear: mtime cache for repeated reads, lazy writes for activation updates, SQLite migration at 50K+ entities.

Configuration

All settings via environment variables or rawthink_mcp/config.py:

Session Lifecycle

RAWThink includes a session close command (/rtclose) that:

1. Exports the current conversation to clean markdown + full transcript + HTML

2. Extracts key entities and relations into the knowledge graph

3. Writes a project-specific handoff file for the next session

4. Updates MEMORY.md with essential context

A SessionStart hook (rawthink-handoff.js) runs when Claude Code starts and loads the most recent handoff + recent qnotes into context automatically.

Session lifecycle currently requires Claude Code. MCP-native session tools are planned for v0.2.

Customization

CLAUDE.md

Edit CLAUDE.md to customize the thinking companion's behavior:

• Role and tone

• Active modes (free-flow, socratic, debate, synthesis, deep-dive, technical, galaxy-brain)

• Epistemic transparency format

• Meta-commands

THINKING_DIRECTIVES.md

Structured discipline for the thinking partnership. Every rule was born from a violation — don't follow mechanically, understand why each exists. Customize to match your workflow.

Obsidian (optional)

Open your vault directory in Obsidian to browse sessions and qnotes visually. The vault uses standard markdown with YAML frontmatter — no plugins needed.

Entity Types

Default entity type is "concept". Common types: concept, decision, rule, insight, question, project.

Relation Types

Canonical types (non-standard accepted with warning): supports, contradicts, evolved_into, depends_on, exemplifies, part_of, caused_by, enables, supersedes, related_to

Roadmap

• Interactive knowledge graph visualization

• Wiki export (agent-browsable markdown per entity)

• .rawthinkignore for vault indexing control

• Graph traversal queries (unexpected connections, multi-hop)

• SQLite backend for 50K+ entities

• MCP-native session tools (no Claude Code dependency)

• Configurable language normalization

License

MIT — see LICENSE.