Intelligent memory sidecar for Claude Code
Passively captures project decisions. Writes them where Claude reads them. Zero effort.

The Problem • Quick Start • How It Works • Architecture • Commands • Contributing

---

The Problem

Every time you start a new Claude Code session, it starts from scratch. It doesn't remember that:

• Your brand uses Inter for headings and #2563EB as the primary color
• Your API follows RESTful conventions with a /api/v1/ prefix
• You chose Drizzle over Prisma after careful evaluation
• Your React components use compound pattern with forwardRef
• That edge case in the payment flow that took you two hours to debug

There are many times when curated context can save significant time, frustration, and make Claude Code feel like magic. Take a website application project — the branding guide that defines colors, fonts, and layout may not always be defined upfront. Even if it was, it may not always be included in the context. It may change over time. If these details aren't in the context and you ask Claude Code to build a new page, it will often pick an entirely different theme, colors, fonts, and layout than what your application already uses.

You end up re-explaining the same decisions in every session. Over and over.

Where curated-context fits

Claude Code has a growing memory ecosystem. Each layer serves a different purpose:

Layer	How it works	What it's good at
Built-in memory	You tell Claude "remember this" and it writes to CLAUDE.md	Explicit, intentional notes you want Claude to keep
claude-mem	Cross-session search over past conversations	Recalling what you discussed — finding prior work, decisions, and context from old sessions
curated-context (this plugin)	Passively extracts high-value information from every session	Automatically remembering project knowledge — design tokens, architecture choices, API patterns, conventions, and gotchas

Built-in memory requires you to stop and say "remember this." claude-mem lets you search your history. curated-context fills the gap between them — it watches your conversations and silently captures the decisions that matter, so the next session starts with full context without you lifting a finger.

All three can run together. They complement each other.

---

Quick Start

# Add the marketplace
claude plugin marketplace add odmarkj/curated-context

# Install the plugin
claude plugin install curated-context

That's it. Two commands. No configuration needed. Works on the host and in devcontainers — the plugin auto-bootstraps into containers on first use.

---

How It Works

curated-context uses a 4-tier cascading pipeline designed to minimize API costs. Most sessions require zero API calls.

Tier	Method	Cost	What It Captures
1	Memory Protocol	Free	Claude self-reports decisions to .claude/decisions.log
2	Structural Extraction	Free	CSS variables, dependencies, configs, API routes from file writes
3	Deterministic Triage	Free	Regex/keyword scoring filters ~75% of conversation noise
4	Claude via claude -p	Your Claude Code sub	Ambiguous conversational decisions (max 30 calls/hour)

What gets captured

• Design tokens — Colors, fonts, spacing, breakpoints from CSS/SCSS/Tailwind
• Architecture decisions — Framework choices, ORMs, state management, auth patterns
• API patterns — Route definitions, naming conventions, versioning schemes
• Configuration — TypeScript settings, linter rules, build tool configs
• Conventions — Naming patterns, file structure, component patterns
• Gotchas — Pitfalls, debugging solutions, edge cases

Where memories are stored

File	Purpose
.claude/rules/cc-*.md	Categorized context files, auto-loaded by Claude Code
CLAUDE.md	Brief summary section with markers
~/.curated-context/store/	JSON backing store (source of truth)

---

Architecture

Claude Code Session
       |
       | Stop hook (every turn)
       v
[Session Accumulator] ── appends to ~/.curated-context/sessions/
       |                   cost: 0 API calls
       |
       | SessionStart hook (next session)
       v
[Background Daemon :7377]
       |
       |──> Tier 1: Decision Log Reader (.claude/decisions.log)
       |──> Tier 2: Structural Extractor (file writes)
       |──> Tier 3: Deterministic Triage (regex scoring)
       |──> Tier 4: Claude Sonnet API (rate-limited last resort)
       |
       v
[Memory Store] ── JSON at ~/.curated-context/store/
       |
       |──> .claude/rules/cc-{category}.md
       |──> CLAUDE.md (marker section)

Key design decisions

• Hooks over MCP — The main Claude session never knows memory extraction is happening. Hooks fire automatically; the sidecar processes independently.
• Deferred processing — Transcripts accumulate during sessions. Processing happens on next session start, so your active rate limits are never touched.
• Sonnet via claude -p — Uses your existing Claude Code subscription. No separate API key needed. Well-scoped classification work, fast and accurate.
• Marker-based CLAUDE.md — Users can see and edit auto-managed sections. Deleting the markers opts out. The daemon never clobbers manual content.

---

Commands

Slash Commands (inside Claude Code)

Command	Description
/curated	Show a summary of all memories for the current project
/curated:teach <memory>	Manually teach a memory (e.g., /curated:teach design primary-color "#2563EB")
/curated:search <query>	Search memories by keyword
/curated-context	Query and manage memories (verbose mode)
/curated-context:status	Daemon health, queue depth, and API usage
/curated-context:forget <key>	Remove a specific memory

CLI

curated-context start [-d]                       # Start daemon (foreground, or -d for background)
curated-context stop                             # Stop daemon
curated-context status                           # Daemon health + memory counts
curated-context memories [--global]              # List all memories
curated-context teach <category> <key> <value>   # Manually add a memory
curated-context search <query>                   # Search memories by keyword
curated-context forget <key> [--global]          # Remove a specific memory
curated-context promote <key>                    # Move project memory to global store

---

Getting Started

Installation

# Add the marketplace (one time)
claude plugin marketplace add odmarkj/curated-context

# Install the plugin
claude plugin install curated-context

For local development, you can also load directly:

claude --plugin-dir /path/to/curated-context

Verify installation

Start a Claude Code session. You should see the hooks register. Then run:

# Inside Claude Code, use the slash command
/curated-context:status

Or from a terminal:

npx curated-context status

How memories appear

After a few sessions, you'll find:

your-project/
  .claude/
    decisions.log          # Claude's self-reported decisions
    rules/
      cc-design.md         # Design tokens, colors, fonts
      cc-architecture.md   # Tech stack, patterns
      cc-api.md            # Route definitions
      cc-conventions.md    # Naming, style rules
  CLAUDE.md                # Summary section with markers

These files are automatically read by Claude Code on every session start.

---

System Requirements

• Node.js >= 20.0.0
• Claude Code with plugin support

---

Documentation

Topic	Description
Getting Started	Installation, first run, verifying it works
Configuration	Rate limits, categories, store locations
Memory Protocol	How the decision log works and how to tune it
Structural Extraction	Which file types are parsed and what's extracted
Troubleshooting	Common issues, daemon logs, debugging
API Reference	Daemon HTTP endpoints, store format, types

For the full technical design document, see DESIGN.md.

---

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Update documentation + SECURITY.md
5. Submit a Pull Request

Development

git clone https://github.com/odmarkj/curated-context.git
cd curated-context
npm install
npm run build        # Compile src/ -> dist/
npm run dev          # Watch mode (tsc --watch)

When contributing, commit dist/ changes alongside src/ changes so end users don't need a build step.

Project structure

curated-context/
├── hooks/              # Plain JS hook handlers (no build step)
│   ├── hooks.json      # Plugin hook configuration
│   ├── capture.js      # Stop hook: accumulate transcripts
│   └── process.js      # SessionStart hook: trigger processing
├── commands/           # Slash command definitions
├── agents/             # Sub-agent definitions
├── src/                # TypeScript source
│   ├── cli.ts          # CLI entry point
│   ├── daemon/         # Express daemon (index, processor, queue, lifecycle)
│   ├── extraction/     # 4-tier pipeline (decision-log, structural, triage, llm)
│   └── storage/        # Memory store, rules writer, CLAUDE.md writer
├── dist/               # Compiled output (committed)
├── bin/                # CLI bin entry
└── .claude-plugin/     # Plugin manifest

---

License

AGPL-3.0-only — see LICENSE for full text.

---

Support

• Bug reports — GitHub Issues
• Feature requests — GitHub Issues
• Questions — GitHub Discussions

---

Sponsors

A special thanks to our project sponsors:

---

_{Built for the Claude Code ecosystem}