LightRAG Memory#

Semantic memory system with vector search + knowledge graph. Replaces reading entire memory files on every request with targeted retrieval (~1-3K tokens vs 30K+).

Quick Setup#

bash

cd skills/lightrag-memory
pip install -r requirements.txt

Set environment variables:

bash

export OPENAI_API_KEY="your-key"
export OPENAI_BASE_URL="https://your-api-endpoint/v1"  # optional, defaults to OpenAI

Or create a .env file in the skill directory.

Commands#

Index memory files#

Index MEMORY.md and memory/*.md from workspace:

bash

python3 scripts/rag.py index

Insert content#

bash

# From file
python3 scripts/rag.py insert --file /path/to/file.md --source "filename"

# From text
python3 scripts/rag.py insert --text "Important fact" --source "manual"

# From stdin
echo "Some text" | python3 scripts/rag.py insert --source "stdin"

Query#

bash

# Hybrid search (best results, costs more API calls)
python3 scripts/rag.py query "What do I know about the user?" --mode hybrid

# Local search (entities + relationships, balanced)
python3 scripts/rag.py query "What projects were discussed?" --mode local

# Naive search (simple vector lookup, cheapest)
python3 scripts/rag.py query "Any notes about deployment?" --mode naive

# Global search (broad context, expensive)
python3 scripts/rag.py query "Summarize everything" --mode global

Query Modes#

ModeWhat it searchesCostBest fornaiveVector embeddings onlyLowestQuick fact lookuplocalEntities + relationshipsLowSpecific entitiesglobalCommunity-level contextHighBroad understandinghybridLocal + globalHighestComprehensive answers

Storage#

Data stored in ~/.openclaw/workspace/lightrag_storage/ by default. Override with LIGHTARG_WORKING_DIR env var.

Integration Pattern#

For agent memory systems, index files on change and query on demand:

bash

# Check if reindex needed (files modified since last index)
find MEMORY.md memory/ -name '*.md' -newer memory/lightrag-last-index.txt

# Reindex if needed
python3 scripts/rag.py index
touch memory/lightrag-last-index.txt

# Query when context needed
python3 scripts/rag.py query "user preferences" --mode naive

Architecture#

• Embeddings: text-embedding-3-small (1536 dim) via OpenAI-compatible API
• LLM: gpt-4o-mini for entity extraction and answer generation
• Storage: JSON-based vector DB + GraphML knowledge graph
• Batching: 8 items per embedding batch, 4 concurrent async requests

Troubleshooting#

OPENAI_API_KEY not set: Ensure env vars are exported or .env exists.

numpy RuntimeError (X86_V2): On older CPUs lacking AVX2, install pip install "numpy<2.0".

Slow first index: Initial indexing processes all files. Subsequent updates are incremental.

Reset storage: rm -rf <storage_dir>/* && python3 scripts/rag.py index