- The Story
- Who is this for?
- How it works
- Requirements
- Quick Start (Let Claude install it!)
- Enable Auto-Retrieval
- After Installation
⚠️ Important! - For Existing Claude Users
- Token Savings
- Directory Structure
- Commands Reference
- Best Practices
- FAQ
- Troubleshooting
- Security
- Credits
After using Continuous-Claude (created by parcadei) for a while, we noticed something: our CLAUDE.md files kept growing. Every time we documented something new, added a guide, or saved a configuration... the file got bigger.
The problem? Claude loads your entire CLAUDE.md on every single prompt. That 30KB file? Loaded 20+ times per session. That's hundreds of thousands of tokens wasted on stuff Claude didn't even need for that prompt.
Why does this matter? Whether you're on Claude Pro ($20/month) or Pro Max ($200/month), you have a monthly token budget. Wasting thousands of tokens per prompt on irrelevant context means less tokens for actual thinking, coding, and building your projects.
The idea: What if Claude could pull in just the context it needs, like building blocks? You ask about your database, Claude grabs the database block. You ask about deployment, Claude grabs the deployment block. Everything else stays on the shelf.
That's BloxCue - context blocks that get cued up when you need them. More tokens for thinking, less tokens wasted on context you don't need.
| If you're... | BloxCue helps you... |
|---|---|
| A Claude Code user | Stop burning tokens on context you're not using |
| Managing multiple configs | Keep docs, guides, and configs organized and searchable |
| Working on several projects | Switch context without reloading everything |
| Hitting token limits | Save ~7,000 tokens per prompt |
| New to Claude Code | Start with good habits from day one |
Before BloxCue:
You: "How do I deploy to production?"
Claude loads: ENTIRE CLAUDE.md (34KB = ~8,500 tokens)
- Your coding standards (not needed)
- Your API documentation (not needed)
- Your 10 different project configs (not needed)
- Your deployment guide (NEEDED!)
- Everything else (not needed)
Result: ~8,500 tokens loaded, only ~800 were relevant
After BloxCue:
You: "How do I deploy to production?"
Claude loads: Just the deployment block (~800 tokens)
- Environment setup
- Deploy commands
- Rollback procedures
Result: ~800 tokens loaded, all relevant
Saved: ~7,700 tokens for thinking & coding
BloxCue works best alongside Continuous-Claude. They're complementary tools that make Claude Code significantly more powerful.
| Tool | What it does |
|---|---|
| Continuous-Claude | Helps Claude remember across sessions (ledgers, handoffs, learnings) |
| BloxCue | Reduces token waste by loading context on-demand |
Think of it this way:
- Continuous-Claude = Claude's memory (what to remember)
- BloxCue = Claude's filing cabinet (where to find it efficiently)
The easiest way to get started: Let Claude set up both tools for you! See the Quick Start section below.
If you prefer manual setup, follow our Continuous-Claude Installation Guide first.
Credit: Continuous-Claude was created by parcadei. Check out the original repository.
Let Claude handle the entire setup for you! This is the smoothest experience - Claude will install both Continuous-Claude and BloxCue, configure everything, and make sure they work together seamlessly.
Copy and paste this to Claude:
I'd like you to set up my Claude Code environment with Continuous-Claude and BloxCue for better context management.
Please:
1. First, install Continuous-Claude from https://github.com/bokiko/continuous-claude-guide
- Follow the setup instructions in that repo
2. Then, install BloxCue from https://github.com/bokiko/bloxcue
- Clone the repo and run the installer
- Ask me which setup I prefer:
* Global (~/.claude-memory) - for personal docs I use across projects
* Project (./claude-memory) - for project-specific docs
* Both - recommended
- Ask me how I want to organize my blocks (by subject, by project, etc.)
- Ask me what categories make sense for my work
- Set up the auto-retrieval hook in settings.json
- Create a sample block to get me started
3. Verify both tools are working together properly
4. Give me a quick summary of what was set up and how to use it
Claude will:
- Install and configure Continuous-Claude
- Install BloxCue with your preferences
- Ask you about your preferred setup (global/project/both)
- Help you choose the right organization and categories
- Configure auto-retrieval hooks
- Create your first block
- Verify everything works together
That's the recommended approach! Claude handles all the technical details while customizing the setup to your needs.
If you prefer to control every step, here's the manual installation:
Follow our Continuous-Claude Installation Guide.
git clone https://github.com/bokiko/bloxcue.git
cd bloxcue./install.shThe installer will ask you a few simple questions:
Question 1: Where to install?
- Global (
~/.claude-memory) - for knowledge you use across all projects - Project (
./claude-memory) - for project-specific docs only - Both - recommended for most users
Question 2: How to organize?
- By subject - guides, references, projects (best for general use)
- By project - project-a, project-b (best for freelancers/agencies)
- Developer - apis, databases, deployment, frontend, backend
- DevOps - servers, networking, monitoring, security
- Minimal - just docs and notes (simplest option)
- Custom - you specify
Question 3: What categories do you need?
Examples for common use cases:
| Use Case | Suggested Categories |
|---|---|
| Web Developer | apis, databases, deployment, frontend, backend |
| DevOps/SysAdmin | servers, networking, monitoring, security |
| Data Scientist | datasets, models, notebooks, pipelines |
| Freelancer | clients, contracts, templates, billing |
| Student | courses, notes, assignments, research |
| General | projects, guides, references, notes |
Pick what makes sense for your work. You can always add more later.
Create a markdown file in your memory folder. Here's an example:
nano ~/.claude-memory/guides/deployment.md---
title: Production Deployment
category: guides
tags: [deployment, production, devops]
---
# Production Deployment
## Prerequisites
- SSH access to production server
- Environment variables configured
- Database migrations ready
## Deploy Steps
1. Run tests locally
2. Push to main branch
3. SSH into server
4. Pull latest changes
5. Run migrations
6. Restart services
## Rollback
If something breaks:
1. Revert to previous commit
2. Run down migrations
3. Restart servicespython3 ~/.claude-memory/scripts/indexer.pypython3 ~/.claude-memory/scripts/indexer.py --search "deployment"You should see your deployment guide in the results!
This step is required for BloxCue to work automatically. The installer handles this, but if you need to set it up manually:
Edit your Claude settings:
nano ~/.claude/settings.jsonAdd this to your hooks section:
{
"hooks": {
"UserPromptSubmit": [{
"hooks": [{
"type": "command",
"command": "~/.claude/hooks/memory-retrieve.sh"
}]
}]
}
}Close and reopen Claude Code for the changes to take effect.
Ask Claude about something you documented:
You: "How do I deploy to production?"
Claude will automatically receive your deployment block as context - no manual search needed!
Note: If you used the "Easy Way" setup above, Claude already configured this for you.
⚠️ Important: BloxCue is installed, but you're still wasting tokens until you slim your CLAUDE.md!
The installer sets up the hooks and directory structure, but it doesn't automatically migrate your existing CLAUDE.md. If you have a large CLAUDE.md file, you're still loading all that content on every prompt.
Ask Claude to slim it for you:
My CLAUDE.md has grown too big. Help me migrate content to BloxCue blocks:
1. Read my current CLAUDE.md
2. Identify distinct topics (deployment, APIs, configs, etc.)
3. Create separate block files in ~/.claude-memory/
4. Slim my CLAUDE.md to essentials only (project name, stack, minimal context)
5. Re-index with: python3 ~/.claude-memory/scripts/indexer.py
Your CLAUDE.md should end up looking like this:
# My Workspace
Knowledge base at `~/.claude-memory/`.
Claude retrieves relevant context automatically via hooks.
## Essentials
- Project: MyApp
- Stack: Node.js, PostgreSQL, RedisThat's it! Everything else lives in your blocks and gets loaded only when needed.
Already have a big CLAUDE.md file? Here's how to migrate:
Tell Claude:
I have an existing CLAUDE.md file that's gotten too big.
Help me migrate it to BloxCue by:
1. Reading my current CLAUDE.md
2. Identifying distinct topics
3. Creating separate block files for each topic
4. Updating my CLAUDE.md to be minimal
Claude will handle the heavy lifting!
- Identify sections in your current CLAUDE.md
- Create a block file for each major section
- Move content from CLAUDE.md to the appropriate blocks
- Trim your CLAUDE.md to just essentials:
# My Workspace
Knowledge base at `~/.claude-memory/`.
Claude automatically retrieves relevant context via hooks.
## Essential Info Only
- Project: MyApp
- Stack: Node.js, PostgreSQLStarting fresh? Even easier:
- Let Claude install Continuous-Claude + BloxCue (see Quick Start)
- Start with a minimal CLAUDE.md
- Add blocks as you go
Your CLAUDE.md stays small forever because everything goes into blocks.
Real numbers from actual usage:
| Metric | Before BloxCue | After BloxCue | Saved |
|---|---|---|---|
| Tokens per prompt | ~8,500 | ~1,000 | ~7,500 tokens |
| Tokens per session (20 prompts) | ~170,000 | ~20,000 | ~150,000 tokens |
Instead of loading your entire knowledge base on every prompt, Claude only loads what's relevant. Those saved tokens go toward:
- More thinking - Claude can reason more deeply about your problem
- Longer sessions - Stay within context limits longer
- Faster responses - Less to process means quicker replies
Best for: General use, mixed work, personal knowledge base
~/.claude-memory/
├── guides/ # How-to guides
├── references/ # Quick reference docs
├── projects/ # Project-specific info
├── configs/ # Configuration templates
├── notes/ # General notes
└── scripts/
└── indexer.py # Search engine
Best for: Freelancers, agencies, multiple client work
~/.claude-memory/
├── client-alpha/
│ ├── requirements.md
│ ├── api.md
│ └── contacts.md
├── client-beta/
│ └── ...
└── scripts/
# Index all your blocks
python3 ~/.claude-memory/scripts/indexer.py
# Search for something
python3 ~/.claude-memory/scripts/indexer.py --search "keyword"
# List all indexed blocks
python3 ~/.claude-memory/scripts/indexer.py --list
# Rebuild index from scratch
python3 ~/.claude-memory/scripts/indexer.py --rebuild- Keep your CLAUDE.md minimal - Just essentials, let blocks handle details
- One topic per file - Better search precision
- Use frontmatter - Title, category, tags help indexing
- Use descriptive tags -
[deployment, production, aws]not just[deploy] - Re-index after adding files - Run the indexer after new docs
Do I need Continuous-Claude to use this?
Technically no, but we strongly recommend it. Continuous-Claude handles session memory (remembering what you were working on), while BloxCue handles knowledge retrieval (finding the right docs). They complement each other perfectly.
Without Continuous-Claude, you'll save tokens but lose the session continuity features.
Will this work with Cursor/VS Code extensions?
This is designed for Claude Code CLI (the terminal tool). It may work with other Claude integrations that support hooks, but we haven't tested them.
How is this different from just using a smaller CLAUDE.md?
Two key differences:
- Scalability - Your knowledge can grow without growing your token usage
- Relevance - Only the blocks relevant to your current question get loaded
A smaller CLAUDE.md means less information available. BloxCue means the right information available at the right time.
What if Claude needs info from multiple blocks?
The retrieval hook can return multiple relevant blocks based on keyword matching. If you ask about "database deployment", it might return both the database block and the deployment block.
Can I use this for project-specific docs too?
Yes! You can have both:
- Global:
~/.claude-memory/for cross-project stuff - Project:
./claude-memory/for project-specific docs
The installer supports setting up both.
How do I back up my blocks?
They're just markdown files! Back them up however you back up other files:
- Git repo (recommended)
- Cloud sync (Dropbox, iCloud, etc.)
- Any backup solution you already use
Can I disable auto-retrieval?
Yes, just remove the hook from your ~/.claude/settings.json. But we recommend keeping it on - that's the whole point of BloxCue!
Install Python 3:
# macOS
brew install python3
# Ubuntu/Debian
sudo apt install python3- Make sure you've run the indexer:
python3 ~/.claude-memory/scripts/indexer.py - Check your files have the
.mdextension - Verify files are in the right directory
- Check your
~/.claude/settings.jsonsyntax (valid JSON?) - Make sure the hook path is correct
- Restart Claude Code after changing settings
See the "For Existing Claude Users" section above - we've got you covered!
Ideas welcome! Some things we'd love help with:
- Better search algorithms (fuzzy matching, embeddings)
- VSCode extension for browsing blocks
- Web UI for managing your memory
- Sync across machines
BloxCue is designed with security in mind:
- Local-only operations - No network activity, no telemetry
- User-controlled data - All files stay on your machine
- Input sanitization - User prompts are sanitized before processing
- Path validation - Prevents directory traversal attacks
- Settings backup - Creates backup before modifying Claude config
See SECURITY.md for the full security audit report.
- parcadei - Creator of Continuous-Claude
MIT - Use it however you want.