Overview
Memory graph commands enable building rich knowledge graphs from thread data with summaries, embeddings, and semantic search capabilities.
Prerequisites: Requires watercooler-cloud[memory] package.
pip install 'watercooler-cloud[memory]'
Commands
memory build
Build memory graph from threads with summaries and embeddings.
Usage
watercooler memory build [options]
Options
Threads directory. Defaults to ./watercooler or $WATERCOOLER_DIR.
Output file path for graph JSON. Alias: -o.
Skip summary generation (faster, less context)
Skip embedding generation (no semantic search)
Git branch context for filtering threads
Examples
Build full graph
Output:
Building memory graph from /path/to/watercooler...
Processing threads:
✓ feature-auth.md (5 entries, 12 chunks)
✓ api-redesign.md (8 entries, 20 chunks)
✓ bug-123.md (3 entries, 6 chunks)
Generating summaries...
✓ 16 entries summarized
Generating embeddings...
✓ 38 chunks embedded
✅ Built graph: 3 threads, 16 entries, 38 chunks
Save graph to file
watercooler memory build --output graph.json
Building memory graph from /path/to/watercooler...
✅ Built graph: 3 threads, 16 entries, 38 chunks
Saved to: graph.json
Fast build (no enrichment)
watercooler memory build --no-summaries --no-embeddings
Building memory graph from /path/to/watercooler...
✅ Built graph: 3 threads, 16 entries, 38 chunks
Build for specific branch
watercooler memory build --branch feature-auth
memory export
Export graph to external format (LeanRAG or JSON).
Usage
watercooler memory export [options]
Options
Input graph JSON file. If not provided, builds from threads.
Threads directory (if building graph)
Export format: leanrag or json
Output path. Directory for LeanRAG, file for JSON. Alias: -o.
Exclude embeddings from export
Examples
Export to LeanRAG
watercooler memory export --format leanrag --output ./leanrag-data
Building graph from /path/to/watercooler...
Exporting to LeanRAG format...
✓ manifest.json
✓ documents/
✓ chunks/
✓ embeddings/
✅ Exported to LeanRAG format: ./leanrag-data
127 documents, 384 chunks
Export pre-built graph
watercooler memory export \
--graph graph.json \
--format leanrag \
--output ./leanrag-data
Export without embeddings
watercooler memory export \
--format leanrag \
--output ./leanrag-data \
--no-embeddings
Export as JSON
watercooler memory export \
--format json \
--output export.json
Building graph from /path/to/watercooler...
✅ Saved graph JSON: export.json
memory stats
Show graph statistics and metadata.
Usage
watercooler memory stats [options]
Options
Graph JSON file. If not provided, builds from threads.
Threads directory (if building graph)
Examples
Show stats for current threads
Output:
Memory Graph Statistics:
Threads: 3
Entries: 16
Chunks: 38
Edges: 24
Hyperedges: 8
Entries w/summaries: 16
Entries w/embeddings: 16
Chunks w/embeddings: 38
Show stats for saved graph
watercooler memory stats --graph graph.json
Show stats for specific directory
watercooler memory stats --threads-dir ~/projects/myapp/watercooler
Graph Structure
Nodes
- Threads: Top-level containers
- Entries: Individual thread entries
- Chunks: Text segments for embedding
Edges
- Thread → Entry: Containment
- Entry → Entry: Temporal sequence
- Entry → Chunk: Decomposition
Hyperedges
- Cross-thread references: Links between related threads
- Topic clusters: Semantic groupings
Enrichment
Summaries
Generated using LLM (requires API key):
export OPENAI_API_KEY=sk-...
watercooler memory build
--no-summaries for faster builds.
Embeddings
Generated for semantic search (requires API key):
export OPENAI_API_KEY=sk-...
watercooler memory build
--no-embeddings if semantic search not needed.
Exported directory structure:
leanrag-data/
├── manifest.json # Index and metadata
├── documents/ # Thread documents
│ ├── feature-auth.json
│ └── api-redesign.json
├── chunks/ # Text chunks
│ ├── chunk-001.json
│ └── chunk-002.json
└── embeddings/ # Vector embeddings
├── emb-001.npy
└── emb-002.npy
Workflows
Initial graph build
# Build with full enrichment
watercooler memory build --output graph.json
# View statistics
watercooler memory stats --graph graph.json
Export for external use
# Build and export in one step
watercooler memory export \
--format leanrag \
--output ./rag-data
# Use with RAG system
python rag_query.py --data ./rag-data --query "auth decisions"
Incremental updates
# Rebuild graph after thread updates
watercooler memory build --output graph.json
# Re-export
watercooler memory export \
--graph graph.json \
--format leanrag \
--output ./rag-data
Quick analysis (no enrichment)
# Fast build for statistics
watercooler memory build --no-summaries --no-embeddings
watercooler memory stats
Build Time
- No enrichment: Fast (seconds)
- With summaries: Medium (API calls per entry)
- With embeddings: Slower (API calls per chunk)
Costs
- Summaries use LLM API (token costs)
- Embeddings use embedding API (per-token costs)
- Costs scale with thread content size
Optimization Tips
- Use
--no-summaries if context not needed
- Use
--no-embeddings if semantic search not needed
- Filter by branch to reduce scope
- Cache graphs with
--output to avoid rebuilds
Error Handling
Missing dependencies
⚠ Missing dependency: openai
Install with: pip install 'watercooler-cloud[memory]'
pip install 'watercooler-cloud[memory]'
API key missing
⚠ Missing dependency: OPENAI_API_KEY not set
export OPENAI_API_KEY=sk-...
Build error
❌ Build error: Thread parse error in feature-auth.md
