claude-memory-bank-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 claude-memory-bank contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# claude-memory-bank
+
+Fully automatic persistent memory for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). One command, zero maintenance.
+
+## The Problem
+
+Claude Code is stateless. Every new conversation starts fresh — your preferences, decisions, progress, and context are lost. You end up repeating yourself across sessions.
+
+## The Solution
+
+```bash
+npx claude-memory-bank-cli init
+```
+
+That's it. This sets up a memory system that Claude automatically reads at the start of every conversation and updates after every task. No slash commands, no manual saves, no workflow triggers.
+
+## What It Creates
+
+```
+your-project/
+├── CLAUDE.md                          # Master file — auto-loads, enforces memory rules
+├── memory-bank/
+│   ├── projectbrief.md                # Scope, requirements, goals
+│   ├── productContext.md              # Why it exists, user problems, UX goals
+│   ├── techContext.md                 # Tech stack, dependencies, dev setup
+│   ├── activeContext.md               # What's being worked on right now
+│   ├── progress.md                    # Done, in-progress, pending, blocked
+│   ├── decisions.md                   # Every decision + reasoning
+│   ├── patterns.md                    # Architecture, code patterns, conventions
+│   ├── troubleshooting.md             # Bugs, fixes, lessons learned
+│   ├── preferences.md                 # User preferences — communication, design
+│   ├── references.md                  # External links, APIs, tools
+│   └── extensions/                    # Overflow when files get large (auto-managed)
+├── .claude/
+│   └── rules/
+│       └── memory-auto-update.md      # Enforces automatic updates every task
+```
+
+## How It Works
+
+1. **`CLAUDE.md`** is automatically loaded by Claude Code at the start of every conversation. It contains rules that tell Claude to read all memory bank files before doing anything.
+
+2. **`.claude/rules/memory-auto-update.md`** enforces that Claude updates the relevant memory files after every task — no user action required.
+
+3. **`memory-bank/`** contains 10 specialized files. Each one auto-updates based on what happens in the conversation:
+
+| File | Updates When |
+|---|---|
+| `projectbrief.md` | Project scope or goals change |
+| `productContext.md` | Product goals or user problems are clarified |
+| `techContext.md` | Dependencies, tools, or setup changes |
+| `activeContext.md` | Every task start/end |
+| `progress.md` | Tasks start, complete, fail, or get added |
+| `decisions.md` | A choice is made between alternatives |
+| `patterns.md` | New code pattern or convention is established |
+| `troubleshooting.md` | Bug found, fixed, or workaround discovered |
+| `preferences.md` | User corrects, approves, or states a preference |
+| `references.md` | External link, API, or tool is mentioned |
+
+4. **Overflow handling:** When any file exceeds ~200 lines, Claude automatically splits it into `memory-bank/extensions/` and keeps the main file as a summary with pointers.
+
+## Features
+
+- **Fully automatic** — zero manual commands after setup
+- **Idempotent** — safe to run `init` again, won't overwrite existing files
+- **Non-invasive** — only creates files, never modifies your existing code
+- **Works with any project** — language-agnostic, framework-agnostic
+- **Scales gracefully** — overflow system prevents files from growing unbounded
+
+## Requirements
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and configured
+- Node.js 14+
+
+## FAQ
+
+**Does this modify my code?**
+No. It only creates markdown files and a `.claude/rules/` directory. Your source code is never touched.
+
+**What if I already have a CLAUDE.md?**
+The `init` command skips any file that already exists. Your existing CLAUDE.md won't be overwritten.
+
+**Can I customize the memory files?**
+Yes. Edit any file in `memory-bank/` — Claude will preserve your changes and build on them.
+
+**How is this different from `.claude/rules/`?**
+Rules tell Claude *how to behave*. The memory bank tells Claude *what it knows*. This package uses rules to enforce the memory system, but the actual memory lives in `memory-bank/`.
+
+**How is this different from other memory bank solutions?**
+Most require manual slash commands (like `/workflow:update-memory`) or manual file management. This one is fully automatic — the rules enforce updates without any user intervention.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command === 'init') {
+  const init = require('../src/init');
+  init(process.cwd());
+} else {
+  console.log('\n  claude-memory-bank — Automatic persistent memory for Claude Code\n');
+  console.log('  Usage:');
+  console.log('    npx claude-memory-bank init    Set up memory bank in current project\n');
+  if (command) {
+    console.log(`  Unknown command: "${command}"\n`);
+  }
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "claude-memory-bank-cli",
+  "version": "1.0.0",
+  "description": "Fully automatic persistent memory system for Claude Code. One command, zero maintenance.",
+  "main": "src/init.js",
+  "bin": {
+    "claude-memory-bank-cli": "./bin/cli.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "memory",
+    "persistent-memory",
+    "ai",
+    "context",
+    "anthropic"
+  ],
+  "author": "Jafar Sadiq <jafar.s@constient.com>",
+  "license": "MIT",
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/init.js

@@ -0,0 +1,79 @@
+const fs = require('fs');
+const path = require('path');
+
+const MEMORY_FILES = [
+  'projectbrief.md',
+  'productContext.md',
+  'techContext.md',
+  'activeContext.md',
+  'progress.md',
+  'decisions.md',
+  'patterns.md',
+  'troubleshooting.md',
+  'preferences.md',
+  'references.md',
+];
+
+function loadTemplate(name) {
+  const tplPath = path.join(__dirname, 'templates', name + '.tpl');
+  return fs.readFileSync(tplPath, 'utf-8');
+}
+
+function writeIfMissing(filePath, content) {
+  if (fs.existsSync(filePath)) {
+    console.log(`  [skip] ${path.relative(process.cwd(), filePath)} (already exists)`);
+    return false;
+  }
+  fs.writeFileSync(filePath, content, 'utf-8');
+  console.log(`  [create] ${path.relative(process.cwd(), filePath)}`);
+  return true;
+}
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function init(targetDir) {
+  console.log('\n  claude-memory-bank — Setting up automatic memory system...\n');
+
+  const memoryDir = path.join(targetDir, 'memory-bank');
+  const extensionsDir = path.join(memoryDir, 'extensions');
+  const rulesDir = path.join(targetDir, '.claude', 'rules');
+
+  ensureDir(memoryDir);
+  ensureDir(extensionsDir);
+  ensureDir(rulesDir);
+
+  let created = 0;
+  let skipped = 0;
+
+  const claudeMd = path.join(targetDir, 'CLAUDE.md');
+  if (writeIfMissing(claudeMd, loadTemplate('CLAUDE.md'))) {
+    created++;
+  } else {
+    skipped++;
+  }
+
+  for (const file of MEMORY_FILES) {
+    const filePath = path.join(memoryDir, file);
+    if (writeIfMissing(filePath, loadTemplate(file))) {
+      created++;
+    } else {
+      skipped++;
+    }
+  }
+
+  const rulePath = path.join(rulesDir, 'memory-auto-update.md');
+  if (writeIfMissing(rulePath, loadTemplate('memory-auto-update.md'))) {
+    created++;
+  } else {
+    skipped++;
+  }
+
+  console.log(`\n  Done. ${created} files created, ${skipped} skipped.`);
+  console.log('  Memory bank is ready. Claude will auto-update it from here.\n');
+}
+
+module.exports = init;

package/src/templates/CLAUDE.md.tpl

@@ -0,0 +1,48 @@
+# Project Memory Bank
+
+This project uses an automatic persistent memory system. Claude MUST follow the rules below every single session.
+
+## Memory System Rules
+
+### On Every Conversation Start
+1. Read ALL files in `memory-bank/` before doing anything else
+2. Check `memory-bank/activeContext.md` to understand what was last being worked on
+3. Check `memory-bank/progress.md` to know current project status
+4. If `memory-bank/extensions/` contains files, read those too
+
+### On Every Task Completion
+1. Update `memory-bank/activeContext.md` with what was just done
+2. Update `memory-bank/progress.md` with current status
+3. If a decision was made, add it to `memory-bank/decisions.md`
+4. If a bug was fixed or discovered, update `memory-bank/troubleshooting.md`
+5. If a new pattern or convention was established, update `memory-bank/patterns.md`
+6. If the user expressed a preference, update `memory-bank/preferences.md`
+7. If an external resource was referenced, update `memory-bank/references.md`
+8. If tech stack or dependencies changed, update `memory-bank/techContext.md`
+9. If project scope or goals changed, update `memory-bank/projectbrief.md` or `memory-bank/productContext.md`
+
+### Overflow Rule
+- If any memory file exceeds ~200 lines, split overflow into `memory-bank/extensions/{filename}-{topic}.md`
+- Keep the main file as a summary with pointers to extension files
+- Extension files follow the same format as their parent file
+
+### Auto-Cleanup
+- Remove outdated entries from `activeContext.md` when tasks are completed
+- Archive completed items in `progress.md` periodically
+- Remove stale references from `references.md` if links are confirmed dead
+
+## Memory Bank Files
+
+| File | Purpose |
+|---|---|
+| `memory-bank/projectbrief.md` | Project scope, requirements, goals |
+| `memory-bank/productContext.md` | Why the project exists, user problems, UX goals |
+| `memory-bank/techContext.md` | Tech stack, dependencies, dev environment setup |
+| `memory-bank/activeContext.md` | Current focus — what's being worked on right now |
+| `memory-bank/progress.md` | Task tracking — done, in-progress, pending, blocked |
+| `memory-bank/decisions.md` | Every decision + reasoning + alternatives rejected |
+| `memory-bank/patterns.md` | Architecture patterns, code conventions, best practices |
+| `memory-bank/troubleshooting.md` | Bugs hit, fixes applied, lessons learned |
+| `memory-bank/preferences.md` | User preferences — communication style, design choices |
+| `memory-bank/references.md` | External links, APIs, tools, documentation |
+| `memory-bank/extensions/` | Overflow files when any main file exceeds ~200 lines |

package/src/templates/activeContext.md.tpl

@@ -0,0 +1,19 @@
+# Active Context
+
+## Current Focus
+[What is currently being worked on]
+
+## Recent Changes
+- [Latest change with date]
+
+## Next Steps
+- [Immediate next task]
+
+## Open Questions
+- [Unresolved questions or blockers]
+
+## Context for Next Session
+[Anything the next conversation needs to know to pick up where this left off]
+
+---
+*Auto-maintained by Claude. Updated at the start and end of every task.*

package/src/templates/decisions.md.tpl

@@ -0,0 +1,12 @@
+# Decisions
+
+## Decision Log
+
+### [Decision Title] — [date]
+- **Choice:** [What was decided]
+- **Alternatives considered:** [Other options]
+- **Reasoning:** [Why this choice was made]
+- **Status:** [active / reversed / superseded]
+
+---
+*Auto-maintained by Claude. Updated when decisions are made, reversed, or reconsidered.*

package/src/templates/memory-auto-update.md.tpl

@@ -0,0 +1,36 @@
+# Memory Bank Auto-Update Rule
+
+You MUST follow these rules automatically. No user command is needed.
+
+## At Conversation Start
+- Read every file in `memory-bank/` and `memory-bank/extensions/` before responding to the user
+- Use this context to understand the project state, what was worked on last, and what's pending
+- Never ask the user to repeat information that exists in memory bank files
+
+## After Every Task
+Update the relevant memory bank files. At minimum, always update:
+- `memory-bank/activeContext.md` — reflect what just changed
+- `memory-bank/progress.md` — mark tasks done/in-progress/pending
+
+Also update these when relevant:
+- `memory-bank/decisions.md` — when a choice was made between alternatives
+- `memory-bank/patterns.md` — when a new code pattern or convention is established
+- `memory-bank/troubleshooting.md` — when a bug is found, fixed, or a workaround is used
+- `memory-bank/preferences.md` — when the user corrects you, approves an approach, or states a preference
+- `memory-bank/references.md` — when an external link, API, or tool is mentioned
+- `memory-bank/techContext.md` — when dependencies, tools, or environment setup changes
+- `memory-bank/projectbrief.md` — when project scope or requirements change
+- `memory-bank/productContext.md` — when product goals or user problems are clarified
+
+## Overflow Management
+- When any memory file approaches ~200 lines, create an extension file at `memory-bank/extensions/{original-filename}-{subtopic}.md`
+- Update the original file to reference the extension: `→ See extensions/{filename}-{subtopic}.md for details`
+- Extension files inherit the same format and purpose as their parent
+
+## Auto-Cleanup
+- When a task in `activeContext.md` is completed, move it to `progress.md` and remove it from active context
+- Remove duplicate information across files
+- Keep files focused and scannable — bullet points over paragraphs
+
+## Critical Rule
+These updates are NOT optional. They happen automatically after every meaningful interaction. The memory bank is only useful if it stays current.

package/src/templates/patterns.md.tpl

@@ -0,0 +1,16 @@
+# Patterns & Conventions
+
+## Architecture Patterns
+- [Pattern name]: [Description and when to use]
+
+## Code Conventions
+- [Convention]: [How it's applied]
+
+## Naming Conventions
+- [Files/variables/functions naming rules]
+
+## Project-Specific Patterns
+- [Patterns unique to this project]
+
+---
+*Auto-maintained by Claude. Updated when new patterns are established or conventions change.*

package/src/templates/preferences.md.tpl

@@ -0,0 +1,22 @@
+# User Preferences
+
+## Communication Style
+- [How the user prefers Claude to communicate]
+
+## Code Style Preferences
+- [Formatting, structure, or style preferences]
+
+## Design Preferences
+- [UI/UX or architecture preferences]
+
+## Workflow Preferences
+- [How the user likes to work — e.g., explain before coding, small PRs, etc.]
+
+## Things to Avoid
+- [Approaches or behaviors the user has rejected]
+
+## Things That Work Well
+- [Approaches the user has approved or praised]
+
+---
+*Auto-maintained by Claude. Updated when the user corrects, approves, or states a preference.*

package/src/templates/productContext.md.tpl

@@ -0,0 +1,21 @@
+# Product Context
+
+## Why This Project Exists
+[The problem this project solves]
+
+## User Problems
+- [Problem 1]
+- [Problem 2]
+
+## How It Should Work
+[Expected user experience and workflow]
+
+## UX Goals
+- [UX goal 1]
+- [UX goal 2]
+
+## Success Metrics
+- [How we know this project is working]
+
+---
+*Auto-maintained by Claude. Updated when product goals or user problems are clarified.*

package/src/templates/progress.md.tpl

@@ -0,0 +1,16 @@
+# Progress
+
+## Completed
+- [Completed task] — [date]
+
+## In Progress
+- [Current task] — started [date]
+
+## Pending
+- [Upcoming task]
+
+## Blocked
+- [Blocked task] — reason: [why]
+
+---
+*Auto-maintained by Claude. Updated when tasks start, complete, fail, or get added.*

package/src/templates/projectbrief.md.tpl

@@ -0,0 +1,24 @@
+# Project Brief
+
+## Project Name
+[Project name will be auto-filled by Claude]
+
+## Overview
+[Brief description of what this project is]
+
+## Goals
+- [Primary goal]
+- [Secondary goals]
+
+## Requirements
+- [Key requirements]
+
+## Scope
+- **In scope:** [What this project covers]
+- **Out of scope:** [What this project does NOT cover]
+
+## Target Users
+- [Who will use this]
+
+---
+*Auto-maintained by Claude. Updated when project scope or goals change.*

package/src/templates/references.md.tpl

@@ -0,0 +1,16 @@
+# References
+
+## External Links
+- [Resource name](URL) — [What it's used for]
+
+## APIs
+- [API name]: [Base URL, auth method, purpose]
+
+## Tools & Services
+- [Tool name]: [How it's used in this project]
+
+## Documentation
+- [Doc link]: [What it covers]
+
+---
+*Auto-maintained by Claude. Updated when external resources, APIs, or tools are referenced.*

package/src/templates/techContext.md.tpl

@@ -0,0 +1,33 @@
+# Tech Context
+
+## Tech Stack
+- **Language:** [e.g., JavaScript, Python]
+- **Framework:** [e.g., React, Express]
+- **Runtime:** [e.g., Node.js 20]
+
+## Dependencies
+[Key dependencies and their purpose]
+
+## Dev Environment Setup
+```bash
+# Steps to set up the project locally
+```
+
+## Build & Run Commands
+- **Install:** `[command]`
+- **Dev:** `[command]`
+- **Build:** `[command]`
+- **Test:** `[command]`
+
+## Project Structure
+```
+[Key directories and their purpose]
+```
+
+## Environment Variables
+| Variable | Purpose | Required |
+|---|---|---|
+| | | |
+
+---
+*Auto-maintained by Claude. Updated when dependencies, tools, or setup changes.*

package/src/templates/troubleshooting.md.tpl

@@ -0,0 +1,18 @@
+# Troubleshooting
+
+## Known Issues
+
+### [Issue Title] — [date]
+- **Symptom:** [What went wrong]
+- **Cause:** [Root cause]
+- **Fix:** [How it was resolved]
+- **Prevention:** [How to avoid it in the future]
+
+## Workarounds
+- [Workaround description]
+
+## Lessons Learned
+- [Lesson from a past bug or issue]
+
+---
+*Auto-maintained by Claude. Updated when bugs are found, fixed, or workarounds are discovered.*