ClaudeClaw+ is open for contributors — the home for heavier ClaudeClaw work

[TerrysPOV]

ClaudeClaw+ is open

@moazbuilds has given his blessing for this repo to exist as a sister project to moazbuilds/claudeclaw. Thank you — claudeclaw is a great foundation and this repo wouldn't exist without it.

ClaudeClaw+ syncs from upstream every day. Everything that lands in claudeclaw lands here too.

---

What is ClaudeClaw+?

ClaudeClaw+ is the place for features that are too heavy, too opinionated, or too architecturally significant for the lightweight upstream repo. If it adds meaningful runtime weight, introduces a new subsystem, or requires design trade-offs the upstream maintainer doesn't want to take on — it belongs here.

The features already in the repo give a clear picture of the scope:

• Policy Engine — deterministic tool governance with audit log and approval queue
• Governance Layer — model routing, token/cost budgets, watchdog for runaway sessions
• Gateway / Events / Escalation — unified message ingestion, replayable event log, retry queue
• Orchestrator — DAG task graph with resumable jobs that survive daemon restarts
• Persistent Memory — cross-session MEMORY.md with dual-layer write guarantee
• CSRF Protection — hardened web UI

---

What belongs here vs. upstream

Contribution type	Where it goes
Bug fixes, small improvements, new integrations	moazbuilds/claudeclaw
New adapters (Slack, WhatsApp, etc.)	moazbuilds/claudeclaw
Anything lightweight and broadly useful	moazbuilds/claudeclaw
New subsystems (governance, orchestration, policy)	ClaudeClaw+
Large architectural changes upstream wouldn't want	ClaudeClaw+
Features requiring significant new runtime dependencies	ClaudeClaw+

If your idea is appropriate for the upstream repo, contribute it there. Work submitted here that is actually lightweight/upstream-suitable won't be merged — it'll be redirected back to moazbuilds/claudeclaw. This keeps both repos coherent.

---

Contributing

• Read CONTRIBUTING.md for the full guide
• Open an issue or discussion first to align on whether the work fits here
• Large PRs, multi-file stacks, and opinionated refactors are welcome
• All ideas are welcome — but scope matters

---

Looking forward to building this out. If you've been sitting on a ClaudeClaw feature idea that's too big for upstream, this is the place.

[Nibbler1250]

Hi @TerrysPOV,

Following up on this — I have a memory pattern that's been working really well in production for me, and I'd love your read on whether it fits Plus or whether you'd rather keep memory.ts as-is.

Context

I read src/memory.ts and prompts/MEMORY_INSTRUCTIONS.md. The single-file structured approach (Current Status / Key Decisions / Project Context / User Preferences / Session Log) is clean — and the per-agent isolation via agents/<name>/MEMORY.md is genuinely useful. So this isn't a "rewrite memory" pitch.

It's more: after a few months of running Claude Code with a different memory layout, I think there's a complementary pattern worth considering as an opt-in extension.

What I'm running

~/agent/MEMORY.md                          # index file, ~150 lines max
~/agent/memory/user_profile.md             # entry: "user" type
~/agent/memory/feedback_communication.md   # entry: "feedback" type
~/agent/memory/project_tacoma_build.md     # entry: "project" type
~/agent/memory/reference_credentials.md    # entry: "reference" type
~/agent/memory/feedback_ibkr_restarts.md   # entry: "feedback" type
... (~15 entries today, growing)

Each entry has frontmatter:

---
name: IBKR Gateway: NE PAS restart pendant heures marché
description: Règle critique, sessions zombies cloud après restart répétés
type: feedback
---

The actual content lives below the frontmatter, structured as:
**Why:** the reason behind this rule
**How to apply:** when this rule kicks in

MEMORY.md is the index, not the content:

- [User profile](memory/user_profile.md) — Simon, MOW IOC, FR québécois
- [IBKR Gateway: do not restart during market hours](memory/feedback_ibkr_restarts.md) — critical rule
- [Tacoma 2017 build](memory/project_tacoma_build.md) — head unit, voice pipeline, Pi 5
... (one line per entry, under ~200 lines so context window doesn't truncate)

Why this pattern instead of single-file

Real-world friction I hit on the Plus pattern after ~50 memories:

1. Scaling — single MEMORY.md over a few months balloons to 1000+ lines. The "Session Log: keep last ~10" rule helps but you still pay the full file in every system prompt.

2. Selective loading — with frontmatter description, the loader (or even Claude itself via @-references) can pull only the entries relevant to the current query. e.g. a "fix this bug" query doesn't need to load reference_credentials.md.

3. Diff hygiene — when memories live in one file, every update pollutes git history with massive diffs. Per-file changes are clean and reviewable.

4. Cross-machine sync — I use a shared simon-memory git repo across 4 machines (ProDesk daemon, laptop, S26 Termux, kiosk). Per-file memories merge cleanly across machines; one big file is a recipe for merge conflicts.

5. Categorization — type: user | feedback | project | reference makes it easy to write rules like "load all feedback entries on startup, but project entries only when relevant". Single file forces you into prose-only structure.

Token economics — the part that gets bigger as Plus scales

This is the argument I think matters most for Plus specifically, because of the orchestrator + sub-agents architecture.

Single-file model: every invocation pays the full MEMORY.md cost in --append-system-prompt, whether that turn needs it or not.

Index + entries model: invocations pay the index (≈ 200 lines, ~1500 tokens) plus only the entries Claude pulls via @-references for the current task.

A concrete back-of-envelope from my own usage:

Scenario	Single-file MEMORY.md	Index + selective entries
Today (~15 entries, ~3500 tokens of memory total)	3,500 tok / call	~1,500 tok index + maybe 1 entry (~300 tok) = 1,800 tok / call
6 months out (~80 entries, ~20k tokens total)	20,000 tok / call	~1,500 tok index + 2-3 entries (~1k tok) = 2,500 tok / call

That's ~88% reduction at scale, every single turn, for every agent.

Plus's orchestrator can spawn multiple sub-agents per task. If each sub-agent on Haiku pays a bloated MEMORY.md every turn, the bill scales linearly with concurrency. The index pattern lets the orchestrator hand each sub-agent only the relevant entries (e.g. a "voice-call" sub-agent gets reference_contacts.md + project_voice_pipeline.md, not the user's git preferences).

Concrete numbers on Haiku ($1/M input):

• Single-file at 20k tokens × 1000 sub-agent calls/day = $20/day just for memory injection
• Index pattern at 2.5k tokens × 1000 calls/day = $2.50/day

That's $525/month saved at moderate scale before counting Sonnet/Opus orchestrator calls. It also helps prompt-cache hit rates: the index is stable across calls (cacheable), entries vary per task (small enough to not blow the cache budget).

This is the part I'd struggle to replicate by just hand-trimming a single file.

Compatibility

Important: this isn't mutually exclusive with the existing pattern. The Plus loader could:

• Default behavior unchanged: load MEMORY.md as content (current).
• If MEMORY.md looks like an index (detected via header pattern or a frontmatter format: index flag), additionally resolve referenced files.
• If ~/agent/memory/ directory exists, optionally treat each *.md with frontmatter as a memory entry.

The current MEMORY_INSTRUCTIONS.md could grow a section: "If you have many memories, prefer the index pattern; here's how."

Trade-offs honestly

• More files — 50 memories = 50 files. Mitigation: index pattern, naming convention (type_topic.md).
• Index drift — index can desync from files. Mitigation: index becomes a generated artifact (regenerated on memory write), or trusted to be hand-maintained (current approach for me, manageable).
• Onboarding curve — new users need to learn frontmatter. Mitigation: keep single-file as default; multi-file is opt-in for power users.

What I'd like to know

• Is this aligned with your vision for memory in Plus, or are you intentionally keeping it simple (MEMORY.md only)?
• If aligned, would you accept a small PR that adds opt-in support for the multi-file index pattern, leaving the default unchanged?
• If not aligned, no problem — I'll keep this pattern in my own agent setup outside of Plus and not push for it. I'm using Plus for the orchestrator/agents/governance subsystems regardless.

I have ~3 months of running this in production with my agent (Greg), so happy to share the actual file structure if you want to inspect before answering. Also happy to draft a small example PR (purely additive, ~150 lines of TS) so you can judge concretely instead of abstractly.

Thanks for opening Plus to contributors — the "heavy work here" framing made this feel like the right place to ask.

— @Nibbler1250

[TerrysPOV]

@Nibbler1250 Thank you for the detailed write-up. Right now I'm more than happy for you to work on this for this repo and I genuinely like the way you have thought about this. i agree this could be a great complementary enhancement. I already have an open issue here from your original comment upstream on CluadeClaw, which i'll assign to you. Thanks you again for your interest and involvement. P.S. Please do review the additional features that exist here as you might find these useful depending on your use case. Please star the repo if you do and tell your friends/colleagues about it.

[Nibbler1250]

Thanks @TerrysPOV — really happy this aligns with where you want Plus to go. I'll wait for the issue assignment on the multi-file memory pattern and start on it once you tag me, so we're not double-tracking with #19.

Order of operations on my side:

1. Finish feat(memory): FTS5 + embedding semantic search over session history #19 first (session-recall TS extension to src/memory.ts) — already in-flight on feat/memory-search in my fork.
2. Once that's merged or in review, switch to the multi-file MEMORY.md index pattern in the issue you mentioned. Will keep it strictly opt-in (single-file remains the default), so existing users see zero change unless they enable it.

P.S. — already started reading through agents.ts, model-router.ts, orchestrator/task-graph.ts, and governance/. The depth here is impressive; star is going up today, and I'll start spreading the word among other devs I know who run heavier ClaudeClaw setups. The "heavy work goes here, lightweight upstream" framing makes contribution decisions trivially clear, which is rare in fork land.