I recently tried setting up claude-cognitive, a working memory system for Claude Code that promises context persistence across sessions. The 15-minute setup guide looked straightforward enough. Three hours later, I finally had it working—but only after discovering several assumptions baked into the default configuration that don't work for most real-world use cases.

Here's what I learned and how I fixed it.

What Claude-Cognitive Does

Before diving into the fixes, let's understand what this tool actually provides:

• Attention-based context routing: Files you mention become "hot" (fully injected into context), then decay to "warm" (headers only), then "cold" (evicted)
• Co-activation: Related files boost each other—mention authentication, and the multitenancy docs warm up too
• State persistence: Your attention scores survive across conversation turns
• Pool coordination: Multiple Claude instances can coordinate via shared state

The system hooks into Claude Code's UserPromptSubmit event to inject relevant documentation before each prompt. In theory, this gives Claude "working memory" about your project.

Problem 1: The Scripts Look in the Wrong Place

After following the setup guide exactly, I ran a test:

echo '{"prompt":"How does authentication work?"}' | python3 ~/.claude/scripts/context-router-v2.py

Nothing. No output. No attention state header.

Digging into the script, I found this:

# Line 452 in the original context-router-v2.py
docs_root = Path(os.environ.get("CONTEXT_DOCS_ROOT", str(Path.home() / ".claude")))

The router looks for documentation in ~/.claude/systems/, ~/.claude/modules/, etc.—the global Claude directory. But the setup guide has you create documentation in your project's .claude/ directory.

The Fix

Make the script prefer project-local docs:

# Priority: CONTEXT_DOCS_ROOT env > project .claude/ > global ~/.claude/
if os.environ.get("CONTEXT_DOCS_ROOT"):
    docs_root = Path(os.environ["CONTEXT_DOCS_ROOT"])
elif Path(".claude").exists():
    docs_root = Path(".claude")
else:
    docs_root = Path.home() / ".claude"

Now the router automatically uses whichever .claude/ directory exists in your current working directory.

Problem 2: Hardcoded Keywords for Someone Else's Project

Even after fixing the docs path, nothing activated. Checking the injection log:

Stats: Hot=0, Warm=0, Cold=4
Activated files: none

The script found my files but couldn't activate them. Why?

The KEYWORDS dictionary—which maps trigger words to documentation files—was hardcoded for the author's specific project:

# Original keywords (lines 79-197)
KEYWORDS: Dict[str, List[str]] = {
    "systems/server-one.md": [
        "server-one", "gpu", "local model", "inference",
        "vram", "cuda", "nvidia-smi"...
    ],
    "systems/server-two.md": [
        "server-two", "edge", "sensory", "perception", "layer 0"...
    ],
    "modules/custom-module.md": [
        "custom", "trajectory", "prediction", "state machine"...
    ],
    # ... 100+ more project-specific keywords
}

The script contained over 100 keywords mapped to files that don't exist in my codebase. No matter what I typed, nothing activated because my project has completely different files and terminology.

The Fix: Config-Driven Keywords

Rather than edit the script every time I switch projects, I refactored it to load keywords from a project-local config file:

def load_project_config() -> Tuple[Dict[str, List[str]], Dict[str, List[str]], List[str]]:
    """
    Load keywords, co-activation, and pinned files from project config.
    Returns (keywords, co_activation, pinned_files) tuple.
    """
    config_paths = [
        Path(".claude/keywords.json"),           # Project-local
        Path.home() / ".claude/keywords.json",   # Global fallback
    ]

    for config_path in config_paths:
        if config_path.exists():
            try:
                with open(config_path) as f:
                    config = json.load(f)
                return (
                    config.get("keywords", {}),
                    config.get("co_activation", {}),
                    config.get("pinned", [])
                )
            except (json.JSONDecodeError, IOError):
                continue

    return ({}, {}, [])

# Load at module level
KEYWORDS, CO_ACTIVATION, PINNED_FILES = load_project_config()

Now each project gets its own .claude/keywords.json:

{
  "keywords": {
    "systems/development.md": [
      "development", "dev", "local", "localhost",
      "database", "migration", "test", "debug"
    ],
    "systems/production.md": [
      "production", "prod", "deploy", "hosting", "ci/cd"
    ],
    "modules/feature-a.md": [
      "feature-a", "component", "service", "handler",
      "your-specific-terms", "class-names", "function-names"
    ],
    "integrations/external-api.md": [
      "external-api", "webhook", "api-key", "integration"
    ]
  },
  "co_activation": {
    "modules/feature-a.md": ["systems/development.md"],
    "integrations/external-api.md": ["modules/feature-a.md"]
  },
  "pinned": ["systems/development.md"]
}

Problem 3: Silent Failures

The most frustrating part of debugging was that the router fails silently. If no files reach HOT or WARM status, it outputs nothing:

# Line 492 in original
if stats["hot"] > 0 or stats["warm"] > 0:
    print(output)

This makes sense in production—you don't want noise when there's nothing relevant. But during setup, you have no idea if the hook is even running.

Debugging Tip

The script logs everything to ~/.claude/context_injection.log. Check it:

tail -50 ~/.claude/context_injection.log

You'll see exactly what's happening:

================================================================================
[2026-01-08T08:41:36.818653] Turn 15
Prompt (first 100 chars): How does authentication work?...
Stats: Hot=0, Warm=0, Cold=4
Total chars: 144
Activated files: none
================================================================================

The Final Architecture

After all fixes, here's what a properly configured multi-project setup looks like:

~/.claude/
├── scripts/                    # Global (shared across all projects)
│   ├── context-router-v2.py   # Modified to load project config
│   ├── pool-auto-update.py
│   ├── pool-loader.py
│   ├── pool-extractor.py
│   └── pool-query.py
├── settings.json              # Global hooks configuration
└── (empty systems/modules/integrations - not needed)

~/projects/your-project/.claude/
├── keywords.json              # Project-specific keywords & co-activation
├── attn_state.json            # Attention state (auto-generated)
├── CLAUDE.md                  # Project overview
├── systems/
│   ├── development.md         # Dev environment docs
│   └── production.md          # Production infrastructure
├── modules/
│   ├── feature-a.md           # Core feature documentation
│   └── feature-b.md           # Another feature
└── integrations/
    └── external-api.md        # Third-party integration docs

Writing Effective Documentation

The context router's value comes from the documentation you feed it. Here's what makes docs useful for this system:

Keep Files Focused

Each file should cover one system, module, or integration. The router injects entire files when they're HOT—a 500-line mega-doc will blow your context budget.

Front-Load the Important Stuff

WARM files only get their first ~25 lines injected. Put the most useful information at the top:

# Feature Name

**Purpose:** One-line description of what this does
**Entry Point:** `src/services/FeatureService.ts`
**Status:** Active

## Quick Reference

**Key Files:**
- `src/services/FeatureService.ts` - Main logic
- `src/controllers/FeatureController.ts` - API endpoints

**Endpoints:**
- `POST /api/feature/action` - Do the thing
- `GET /api/feature/:id` - Get the thing

Choose Keywords Carefully

Keywords are matched against the lowercased prompt. Include:

• Technical terms (api, webhook, middleware, database)
• File/class names (UserService, OrderController)
• Common phrasings (how does X work, set up Y)

Avoid overly generic words that would trigger false positives.

Is It Worth It?

After all this setup, does claude-cognitive actually help?

Yes, but with caveats.

When configured properly, asking "How does authentication work?" now gives Claude immediate context about my JWT implementation, tenant membership model, and test accounts. That's genuinely useful for complex codebases.

But the setup cost is significant. You need to:

1. Write project documentation (which you should do anyway)
2. Curate keywords that match how you actually ask questions
3. Maintain the docs as your project evolves

For small projects, this is overkill. For larger codebases where you're constantly context-switching between subsystems, the attention-based routing can save real time.

Quick Start for Your Project

If you want to try this modified setup:

1. Clone and install scripts:

git clone https://github.com/GMaN1911/claude-cognitive.git ~/.claude-cognitive
cp ~/.claude-cognitive/scripts/*.py ~/.claude/scripts/
chmod +x ~/.claude/scripts/*.py

2. Apply my patches to ~/.claude/scripts/context-router-v2.py:

Replace the docs_root logic (~line 450):

if os.environ.get("CONTEXT_DOCS_ROOT"):
    docs_root = Path(os.environ["CONTEXT_DOCS_ROOT"])
elif Path(".claude").exists():
    docs_root = Path(".claude")
else:
    docs_root = Path.home() / ".claude"

Replace the KEYWORDS/CO_ACTIVATION section (~line 68-174) with the load_project_config() function shown above.

3. Create project config:

mkdir -p your-project/.claude/{systems,modules,integrations}
# Create keywords.json with your project's keywords
# Create documentation files

4. Configure hooks in ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [
        {"type": "command", "command": "python3 ~/.claude/scripts/context-router-v2.py"}
      ]
    }]
  }
}

5. Set your instance ID:

echo 'export CLAUDE_INSTANCE=A' >> ~/.zshrc

Conclusion

Claude-cognitive is a clever system with a flawed default configuration. The core ideas—attention decay, co-activation, tiered context injection—are sound. But the implementation assumes you're running a specific project and storing everything globally.

With a few patches to support project-local configuration, it becomes genuinely useful for managing context across large codebases. The setup investment pays off when you stop needing to re-explain your architecture every few prompts.

I've opened a PR to add per-project keyword configuration to the main repository. Hopefully this makes the tool more accessible to those who routinely work outside of a monorepo.

I upgrade my rails project and tend to run on the latest stable version. Doing those upgrades tends to wipe out my configs so I will usally do them manually. In this case I missed a really cool feature - the health check endpoint at \up.

Setting this up is fairly easy! Add these lines to the top of your routes file:

Rails.application.routes.draw do
  # Reveal health status on /up that returns 200 if the app boots with no exceptions, otherwise 500.
  # Can be used by load balances and uptime moniors to verify the app is live.
  get 'up' => 'rails/health#show', as: :rails_health_check
...

Now if you visit your running app's \up path you should be presented with a green screen for a running app, and a red one for a failed.

If you host on fly.io you can take advantage of this new endpoint by modifying your fly.toml to include the health checks as shown here:

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = true
  auto_start_machines = true
  min_machines_running = 1
  processes = ["app"]

[checks]
  [checks.status]
    port = 3000
    type = "http"
    interval = "10s"
    timeout = "2s"
    grace_period = "5s"
    method = "GET"
    path = "/up"
    protocol = "http"
    tls_skip_verify = false
    [checks.status.headers]
      X-Forwarded-Proto = "https"

DEPRECATION WARNING: Rails.application.secrets is deprecated in favor of Rails.application.credentials

I recently upgraded to Rails 7.1 for my project, kidcarekit (a daycare management Saas) and upon running my tests, discovered a dreaded DEPRECATION WARNING. Well, at least we caught it before 7.2 was released!

Being relatively new to rails, I wasn't immediately clear how to update my project to use the new Rails.application.credentials instead of secrets. My application.rb file looked like this, and the error pointed at Bundler.require(*Rails.groups)

require_relative "boot"

require "rails/all"

# Require the gems listed in Gemfile, including any gems
# you've limited to :test, :development, or :production.
Bundler.require(*Rails.groups)

module Kidcarekit
...	

After some digging it looks like this was due to the Devise gem having a SecretKeyFinder that looked like this:

# frozen_string_literal: true

module Devise
  class SecretKeyFinder
    def initialize(application)
      @application = application
    end

    def find
      if @application.respond_to?(:credentials) && key_exists?(@application.credentials)
        @application.credentials.secret_key_base
      elsif @application.respond_to?(:secrets) && key_exists?(@application.secrets)
        @application.secrets.secret_key_base
      elsif @application.config.respond_to?(:secret_key_base) && key_exists?(@application.config)
        @application.config.secret_key_base
      elsif @application.respond_to?(:secret_key_base) && key_exists?(@application)
        @application.secret_key_base
      end
    end

    private

    def key_exists?(object)
      object.secret_key_base.present?
    end
  end
end

The FIX - I am able to mitigate the warning by implementing a Devise-specific secret key in devise.rb, but I'd like to keep it using the secret_key_base. So, in light of Rails 7.1 just being release yesterday, I've decided to wait for Devise to catch up!

Transactional emails are the lifeblood of web applications, delivering crucial information and updates to users. But who said transactional emails have to be boring? In this blog post, we will explore how the powerful combination of Rails Action Mailer and MailerSend can infuse whimsy and enchantment into your transactional email communications. Not really... but you can get up and delivering production transactional emails without getting out your credit card.

My project, kidcarekit, has reached the point where I want to test things like email verification and provide the ability for users to reset their password via email. As it turns out with Rails setting up SMTP is as simple as adding a few lines to your environment files.

In development I'm using the letter_opener gem that automatically pops up the email your app would've sent in a new browser tab. It's insaely powerful and easy to setup. In your gemfile add (under development only so avoid loading this gem in your production environment) like this:

group :development do
  # Don't send emails in development
  gem 'letter_opener'
end

You will also need to modify your development.rb file to use your new gem.

  # Config letter opener for development.
  config.action_mailer.delivery_method = :letter_opener
  config.action_mailer.perform_deliveries = true

Bundle install and then run your app to the point of an email being generated and you should be presented with your test email in a new browser tab. NEAT!

Now for your production emails. I'm using the free tier of MailerSend via SMTP which is super easy to configure for your Rails app. As of writing this post they have a super generous free tier; 3000 emails a month then 1$ for each additional thousand emails your app generates.

I will leave setting up and verifying your account with MailerSend an exercise to the reader, but once you have it is simple to configure Rails via the production.rb environment configuration to use the SMTP server provided by MailerSend.

  # Set default_url_options host
  config.action_mailer.default_url_options = { host: "www.kidcarekit.com" }
  config.action_mailer.delivery_method = :smtp

  # SMTP settings for Mailerlite
  config.action_mailer.smtp_settings = {
  :address => ENV["MAILERSEND_SERVER"],
  :port => 587,
  :user_name => ENV["MAILERSEND_USERNAME"],
  :password => ENV["MAILERSEND_PASSWORD"],
  }

Mine looks like this. I host my application on fly.io now that Heroku's value proposition has decreased. One of the beautiful things about fly.io is the management of secrets via the environment. I don't recommend storing your actual credentials in your source code.

Thanks for sticking around and happy building!

I ran into a perplexing issue today with the Rails 7.0.6 model generator not actually generating the references tag.

Here's what I was attempting to do:

rails g model Waitlist name:string --primary-key-type=uuid daycare:references

The model it created should a string field, name and references to the daycare table. Or so I thought. No matter how many times I ran this generator and the subsequent db:migrate my reference fields just didn't exist.

I proceeded to rubber duck the problem to a friend on Discord and no sooner had I typed it out and hit Send that I realized that the order probably matters.

rails g model Waitlist name:string daycare:references --primary-key-type=uuid

MAGIC - everything was generated as expected. Happy rubying!

This error had me stumped for a few hours the other night. I'm using fly.io to host a project that I'm working on to help manage in-home child care providers run their business.

 > [build 6/6] RUN SECRET_KEY_BASE=DUMMY ./bin/rails assets:precompile:                                             
#15 3.687                                                                                                           
#15 3.687 Rebuilding...                                                                                             
#15 3.734 Error: Cannot find module '@tailwindcss/forms'                                                            
#15 3.734 Require stack:
#15 3.734 - /rails/config/tailwind.config.js
#15 3.734     at Function.Module._resolveFilename (node:internal/modules/cjs/loader:933:15)
#15 3.734     at Function._resolveFilename (pkg/prelude/bootstrap.js:1955:46)
#15 3.734     at Function.resolve (node:internal/modules/cjs/helpers:108:19)
#15 3.734     at _resolve (/snapshot/tailwindcss/node_modules/jiti/dist/jiti.js:1:241025)
#15 3.734     at jiti (/snapshot/tailwindcss/node_modules/jiti/dist/jiti.js:1:243309)
#15 3.734     at /rails/config/tailwind.config.js:54:5
#15 3.734     at jiti (/snapshot/tailwindcss/node_modules/jiti/dist/jiti.js:1:245784)
#15 3.734     at /snapshot/tailwindcss/lib/lib/load-config.js:37:30
#15 3.734     at loadConfig (/snapshot/tailwindcss/lib/lib/load-config.js:39:6)
#15 3.734     at Object.loadConfig (/snapshot/tailwindcss/lib/cli/build/plugin.js:135:49) {
#15 3.734   code: 'MODULE_NOT_FOUND',
#15 3.734   requireStack: [ '/rails/config/tailwind.config.js' ]
#15 3.734 }
#15 3.744 rails aborted!
#15 3.744 Command failed with exit 1: /rails/vendor/bundle/ruby/3.2.0/gems/tailwindcss-rails-2.0.29-x86_64-linux/exe/x86_64-linux/tailwindcss
...<removed some unuseful stack trace here>...
#15 3.745 Tasks: TOP => assets:precompile => tailwindcss:build
#15 3.745 (See full trace by running task with --trace)
------
Error: failed to fetch an image or build from source: error building: executor failed running [/bin/sh -c SECRET_KEY_BASE=DUMMY ./bin/rails assets:precompile]: exit code: 1

If this was my first deploy I'd think that something was going on with fly but this had been working perfectly. Then I realized it happened once I added Flowbite / tailwindcss to the mix. There are some workarounds to get Flowbite working with Turbo but that involved mixing importmap and node_modules a bit.

So the fix was to delete my DockerFile, but not the fly.toml and regenerate the DockerFile with fly deploy. The let the fly console appropriately add the node build steps and allowed my deployments to work as intended.

As 2022 comes to a close, it's time to look back and reflect on the ups and downs of the past 12 months. For me, this year brought many exciting and memorable experiences, including starting a new job, diving into the world of Ruby on Rails, and welcoming my second child into the world. It also brought its fair share of challenges, including several hospitalizations for my kids due to respiratory syncytial virus (RSV).

Looking back, it's clear that 2022 was a year full of growth and change. From learning new skills and adapting to a fully remote work environment, to navigating the joys and challenges of parenthood, it's been a whirlwind of a year. I want to share some of the highlights and lessons learned from my personal journey in 2022.

One of the biggest changes for me in 2022 was starting a new job. After spending a decade at my previous company, I decided it was time for a change and took a leap of faith by accepting a new position at a different company. The transition wasn't always easy, but it ultimately proved to be a great decision.

In my new role, I have been able to take on more responsibility and challenge myself in new ways. I have also had the opportunity to work with a talented and supportive team, which has been incredibly rewarding.

One of the biggest adjustments for me has been working in a fully remote environment. While I had worked remotely before, this was the first time I had done so full-time. It took some getting used to, but I have come to appreciate the flexibility and autonomy that comes with remote work.

One of the biggest challenges I faced in my new job was the requirement to learn a new programming language. After years of working with C#, I was tasked with learning Ruby on Rails, a popular web application framework.

The learning process was not always easy, and there were certainly moments when I felt overwhelmed or frustrated (and occasionally still do). However, I found that the more I practiced and applied what I was learning, the more confident and competent I became.

I was also fortunate to have a great support system at my new job, including fellow developers and online resources, who were there to offer guidance and encouragement.

One of the biggest highlights of 2022 for me was welcoming my second son, Desmond, into the world. As a parent, there is nothing quite like the joy and love that comes with a new child, and Desmond has brought so much happiness and laughter into our lives.

Having a second child was certainly a different experience than the first time around. I was more confident and prepared in some ways, but there were also new challenges and uncertainties to navigate.

One of the most memorable moments of the year was watching my older son, Osborne, who is now a big brother, bond with Desmond and take on his new role with pride and joy. It has been a true joy to watch the two of them grow and develop together.

Unfortunately, 2022 was not all sunshine and rainbows for our family. My kids both ended up hospitalized with respiratory syncytial virus (RSV), a common but highly contagious respiratory illness. It was a scary and stressful time, and seeing my little ones hooked up to machines and struggling to breathe was heart-wrenching.

However, the hospital staff were amazing and did everything they could to make sure my kids received the best possible care. They were also very supportive of us as parents, helping us navigate the situation and providing resources and guidance.

While the hospitalizations were certainly a low point of the year, I am grateful for the care my kids received and for the lessons learned from the experience. It reminded me of the importance of taking care of our health and being prepared for the unexpected.

Overall, the hospitalizations for RSV in 2022 were a challenging experience, and one that I hope to never have to repeat.

As I look back on the ups and downs of 2022, it's clear that it was a year of growth and change. From starting a new job and learning Ruby on Rails, to welcoming my second child and facing hospitalizations for RSV, it's been a whirlwind of a year.

Looking ahead to 2023, I am focusing on getting my health back on track. I have a new doctor and have taken up cycling with my new Peloton bike, and I am determined to make healthy lifestyle choices and prioritize self-care.

One of the things I am most excited about in 2023 is watching my children continue to grow and develop. My older son is already showing signs of independence and creativity, and my younger son, Desmond, is growing and changing every day.

As a parent, there is nothing quite like the joy and pride that comes with watching your children learn and grow. I can't wait to see what new milestones and achievements my kids will reach in the coming year, and to be there to support and encourage them every step of the way.

I am also looking forward to continuing my journey with Ruby on Rails and growing in my new job. It's going to be a great year, and I can't wait to see what it has in store.

Some devices on my network were unable to access Plex directly since migrating to OPNSense with Unbound DNS.

After much troubleshooting adding plex.direct to Services->Unbound DNS->Advanced->Private Domains and applying/restarting Unbound those devices now connect directly.

Happy (local) streaming!