LightRAG Claude Skills

Persistent memory for Claude Code via LightRAG knowledge graphs.

7 slash-command skills + 2 auto-hooks that give Claude Code the ability to remember decisions, preferences, project context, and learnings across sessions.

Prerequisites

• LightRAG server running and accessible
• Node.js 18+ (for fetch() in hooks)
• Claude Code installed

Quick Install

git clone https://github.com/butchokoy25/lightrag-claude-skills.git
cd lightrag-claude-skills
bash install.sh

The installer copies skills and helpers, merges MCP config, and prints next steps. Then:

1. Edit ~/.mcp.json — replace placeholders with your server details
2. Register the hooks (see Hooks Setup below)
3. Set env vars and restart Claude Code

Manual Install

1. Copy helpers:

   cp helpers/rag-prime.mjs ~/.claude/helpers/
   cp helpers/rag-sync.mjs ~/.claude/helpers/
   

2. Copy skills:

   cp -r skills/rag-* ~/.claude/skills/
   

3. Copy or merge MCP config:

   # New install:
   cp .mcp.json.example ~/.mcp.json
   
   # Existing config — merge the lightrag + lightrag-projects entries manually
   

4. Register hooks (see below)

5. Set env vars in your shell profile:

   export LIGHTRAG_SERVER_URL="http://YOUR_LIGHTRAG_HOST:YOUR_PERSONAL_PORT"
   export LIGHTRAG_API_KEY="YOUR_API_KEY"  # only needed for project instances
   

6. Restart Claude Code.

Hooks Setup

The helpers need to be registered as Claude Code hooks in ~/.claude/settings.json. Copying the files alone does not activate them.

Add these entries to your settings.json (create the file if it doesn't exist, merge if it does):

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "node $HOME/.claude/helpers/rag-prime.mjs"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "node $HOME/.claude/helpers/rag-sync.mjs"
          }
        ]
      }
    ]
  }
}

If you already have hooks configured, merge these entries into your existing SessionStart and Stop arrays.

What the hooks do

Hook	Event	Behavior
rag-prime.mjs	SessionStart	Fetches context from your personal LightRAG graph and prints it to stdout so Claude has memory from prior sessions. Validates auth, 5s/15s timeouts, max 3000 chars. Silent fail.
rag-sync.mjs	Stop	Scans ~/.claude/projects/*/memory/ and ~/.claude/skills/rag-*/ for modified .md files and pushes them to LightRAG. Only advances the sync marker on successful inserts. Silent fail.

Auth Modes

LightRAG supports two auth patterns. These skills handle both:

Guest / Disabled Mode (Personal Instance)

No API key needed. Skills fetch a Bearer token from the server:

GET /auth-status → { access_token: "..." }
→ Authorization: Bearer <token>

Used by: rag-query, rag-remember, rag-sync, and both hooks.

Enabled Mode (Project Instance)

Requires an API key via header:

X-API-Key: <your-api-key>
→ Set via LIGHTRAG_API_KEY env var

Used by: rag-project-query, rag-project-remember, rag-project-sync, rag-setup-project.

Configuration

Env Var	Purpose	Required
LIGHTRAG_SERVER_URL	Personal LightRAG instance URL	Yes
LIGHTRAG_API_KEY	API key for project LightRAG instance	Only for project skills

Skills Reference

Skill	Trigger	What it does
rag-query	/rag-query	Query personal knowledge graph (hybrid/local/global/naive modes)
rag-remember	/rag-remember	Store a fact or decision to personal graph immediately
rag-sync	/rag-sync	Review session learnings, confirm with user, batch-insert to personal graph
rag-project-query	/rag-project-query	Query project-specific knowledge graph
rag-project-remember	/rag-project-remember	Store project-specific knowledge
rag-project-sync	/rag-project-sync	End-of-session project memory sync
rag-setup-project	/rag-setup-project	Configure LightRAG MCP for a Cursor project

Architecture

┌─────────────────────────────────────────────────┐
│                  Claude Code                     │
│                                                  │
│  SessionStart ──► rag-prime.mjs ──┐              │
│                                   │ context      │
│  /rag-query ──────► SKILL.md ─────┤              │
│  /rag-remember ───► SKILL.md ─────┤              │
│  /rag-sync ───────► SKILL.md ─────┤              │
│                                   ▼              │
│  Stop ────────────► rag-sync.mjs                 │
│                                                  │
└──────────────────┬──────────────────┬────────────┘
                   │                  │
        Bearer token auth      X-API-Key auth
                   │                  │
                   ▼                  ▼
       ┌────────────────────┐ ┌────────────────────┐
       │  Personal LightRAG │ │  Project LightRAG  │
       │  (guest mode)      │ │  (auth enabled)    │
       │  :PERSONAL_PORT    │ │  :PROJECT_PORT     │
       └────────────────────┘ └────────────────────┘

File Structure

lightrag-claude-skills/
├── README.md
├── LICENSE
├── .mcp.json.example          ← MCP server config template
├── install.sh                 ← Copies skills + helpers, merges MCP config
├── helpers/
│   ├── rag-prime.mjs          ← SessionStart hook
│   └── rag-sync.mjs           ← Stop hook (auto-sync)
└── skills/
    ├── rag-query/SKILL.md
    ├── rag-remember/SKILL.md
    ├── rag-sync/SKILL.md
    ├── rag-setup-project/SKILL.md
    ├── rag-project-query/skill.md
    ├── rag-project-remember/skill.md
    └── rag-project-sync/skill.md

License

MIT