Skip to content

Commit 01100be

Browse files
puppe1990puppe1990
committed
Enhance README.md with detailed project overview, features, installation instructions, and usage guidelines for Memory Bank for Agents (Rails). Added sections for custom development guides and contributor setup.
1 parent 3fc2777 commit 01100be

File tree

1 file changed

+307
-7
lines changed

1 file changed

+307
-7
lines changed

‎README.md‎

Lines changed: 307 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,28 @@
11
# Memory Bank for Agents (Rails)
22

3-
A Rails engine that bootstraps AI-ready development docs and project memory for Ruby on Rails teams. It ships generators, rake tasks, and optional IDE rules to keep context consistent across teammates and AI agents.
3+
A Rails engine that bootstraps **AI-ready development docs** and **project memory** for Ruby on Rails teams. It ships generators, rake tasks, and optional IDE rules to keep context consistent across teammates and AI agents.
44

5-
## Installation
5+
## 🚀 Overview
6+
7+
**Memory Bank for Agents (Rails)** installs a structured documentation system, SPEC-driven feature workflow, and optional editor rules. Perfect for:
8+
9+
* Rails (full-stack or API-only)
10+
* Plain Ruby service objects / gems inside your monorepo
11+
* Background jobs (Sidekiq/ActiveJob) and service-oriented codebases
12+
13+
## ✨ Features
14+
15+
* 🎯 **AI-Ready Setup**: Rails generators scaffold an opinionated docs workspace for agent collaboration
16+
* 📚 **Memory Management**: Organized Markdown docs for durable project knowledge
17+
* ⚙️ **Rails Native**: Installers, rake tasks, config under `config/memory_bank.yml`
18+
* 🧪 **SPEC-Driven Development**: Generators for requirements, design, and task breakdowns
19+
* 🧰 **Editor/Tooling Hooks**: Optional `.cursorrules`, RuboCop base config, and Solargraph hints
20+
* 🔧 **Custom Guides**: Point to your company playbooks and have them copied in on install
21+
* 🧯 **Zero Config Defaults**: Sensible paths; override via YAML when you need to
22+
23+
---
24+
25+
## 📦 Installation
626

727
Add to your `Gemfile`:
828

@@ -17,18 +37,298 @@ bundle install
1737
rails g memory_bank:install
1838
```
1939

20-
One-off (no Gemfile):
40+
The installer will create `config/memory_bank.yml` and (optionally) copy a default guide and `.cursorrules`.
41+
42+
**One-off (no Gemfile)**
43+
44+
```bash
45+
bundle exec rails runner 'MemoryBank::CLI.run("init")'
46+
```
47+
48+
> Useful in sandboxes or CI steps, but the gem install is recommended.
49+
50+
---
51+
52+
## 🎮 Usage
53+
54+
### Supported Development Environments
55+
56+
**Built-in Rails Guides**
57+
58+
* 🌐 **Rails Web** – MVC, Turbo/Stimulus, Hotwire workflows
59+
* 🧱 **Rails API** – API-only, serializers, auth patterns
60+
* 🔌 **Background Jobs** – ActiveJob/Sidekiq patterns
61+
62+
**Custom Guides**
63+
64+
* 🔧 **Company Standards** – your internal conventions and checklists
65+
* 🧩 **Team Workflows** – squad-specific processes and release rituals
66+
* 🏗 **Architecture Patterns** – service objects, DDD, microservices boundary notes
67+
68+
Each guide provides:
69+
70+
* Customized development guidelines and best practices
71+
* Architecture patterns tailored to Rails projects
72+
* Optional `.cursorrules` and RuboCop base config
73+
* Documentation templates for fast onboarding
74+
75+
---
76+
77+
## ⚡ Quick Start
78+
79+
From your Rails app:
2180

2281
```bash
23-
bundle exec rails runner 'MemoryBankRails::CLI.run("init")'
82+
cd your-rails-app
83+
rails g memory_bank:install
84+
```
85+
86+
Choose a development environment when prompted:
87+
88+
```
89+
🚀 Memory Bank Initializer (Rails)
90+
=================================
91+
92+
📝 Available development guides:
93+
1) 📦 Rails Web - MVC/Turbo/Stimulus
94+
2) 📦 Rails API - API-only patterns
95+
3) 📦 Background Jobs - ActiveJob/Sidekiq
96+
4) 🔧 Company Rails (Custom)
97+
5) 🔧 Microservices (Custom)
98+
99+
? What type of memory bank would you like to install?
100+
> Rails Web - MVC/Turbo/Stimulus
101+
Rails API - API-only patterns
102+
Background Jobs - ActiveJob/Sidekiq
103+
Company Rails (Custom)
104+
Microservices (Custom)
24105
```
25106

26-
## Rake tasks
107+
Or run the task directly:
108+
109+
```bash
110+
rake memory_bank:init
111+
```
112+
113+
---
114+
115+
## 📁 Project Structure
116+
117+
After initialization, you’ll see:
118+
119+
```
120+
your-rails-app/
121+
├─ .memory_bank/ # AI memory & docs system
122+
│ └─ developmentGuide.md # Copied from selected guide
123+
├─ .specs/ # Feature specs (empty initially)
124+
├─ .cursorrules # Optional IDE rules (from guide)
125+
└─ config/memory_bank.yml # Memory Bank configuration
126+
```
127+
128+
> You can expand `.memory_bank/` with more docs as your project grows.
129+
130+
---
131+
132+
## 🧠 Creating Memory Bank Files
133+
134+
Initialize the full docs suite:
27135

28136
```bash
29-
rake memory_bank:init GUIDE=rails_web WITH_RULES=true
30137
rake memory_bank:initialize
31-
rake memory_bank:spec:new FEATURE=my-feature
138+
```
139+
140+
This creates:
141+
142+
* `projectBrief.md` – foundation and goals
143+
* `productContext.md` – product vision & UX
144+
* `activeContext.md` – current focus & decisions
145+
* `systemPatterns.md` – architecture & patterns
146+
* `techContext.md` – stack & tooling
147+
* `progress.md` – status, milestones, known issues
148+
149+
---
150+
151+
## 📋 SPEC-Driven Feature Development
152+
153+
Generate a new SPEC:
154+
155+
```bash
156+
rake memory_bank:spec:new FEATURE="export-memory-bank-to-json"
157+
```
158+
159+
This produces:
160+
161+
```
162+
.specs/
163+
└─ export-memory-bank-to-json/
164+
├─ requirements.md # user stories & acceptance criteria
165+
├─ design.md # architecture & component design
166+
└─ tasks.md # actionable tasks & checklist
167+
```
168+
169+
**Workflow**
170+
171+
1. **Requirements** – capture stories and acceptance criteria
172+
2. **Design** – choose patterns, boundaries, data flow
173+
3. **Tasks** – break down implementation; track progress
174+
175+
---
176+
177+
## 🧠 Memory Bank System
178+
179+
**Core Components**
180+
181+
* **Project Brief** – scope and success criteria
182+
* **Product Context** – UX goals and problem framing
183+
* **Active Context** – what changed; what’s next
184+
* **System Patterns** – shared decisions & tradeoffs
185+
* **Tech Context** – runtime, deps, CI/CD, linting
186+
* **Progress** – done/blocked/backlog transparency
187+
188+
**Benefits**
189+
190+
* Consistent context for AI agents & humans
191+
* Durable knowledge retention and onboarding
192+
* Fewer regressions; clearer decisions trail
193+
194+
---
195+
196+
## 🔧 Custom Development Guides
197+
198+
Point the engine to your guide folder and manage entries:
199+
200+
```bash
201+
rails memory_bank:configure
202+
```
203+
204+
You’ll be prompted for a directory (can be outside the repo):
205+
206+
```
207+
~/custom-dev-guides/
208+
├─ company-rails/
209+
│ ├─ developmentGuide.md
210+
│ └─ .cursorrules # optional
211+
├─ microservices/
212+
│ ├─ developmentGuide.md
213+
│ └─ .cursorrules # optional
214+
└─ legacy-ruby/
215+
├─ developmentGuide.md
216+
└─ .cursorrules # optional
217+
```
218+
219+
**Required files**
220+
221+
* `developmentGuide.md` – your standards & practices
222+
* `.cursorrules` (optional) – IDE/agent hints
223+
224+
You can also set the folder in `config/memory_bank.yml`:
225+
226+
```yml
227+
memory_bank:
228+
guides_path: "~/custom-dev-guides"
229+
default_guide: "company-rails"
230+
```
231+
232+
---
233+
234+
## 🔧 Development (for contributors to the gem)
235+
236+
**Prerequisites**
237+
238+
* Ruby 3.1+
239+
* Rails 7.0+
240+
* Bundler
241+
242+
**Local setup**
243+
244+
```bash
245+
git clone https://github.com/your-org/memory_bank_rails.git
246+
cd memory_bank_rails
247+
bundle install
248+
249+
# run specs
250+
bundle exec rspec
251+
252+
# lint
253+
bundle exec rubocop
254+
255+
# run in a dummy Rails app (engine test)
256+
bin/rails app:template LOCATION=spec/dummy/template.rb
257+
```
258+
259+
**Common scripts**
260+
261+
* `rspec` – run test suite
262+
* `rubocop` – lint/fix
263+
* `rake build` – build gem
264+
* `rake release` – release to RubyGems (maintainers)
265+
266+
---
267+
268+
## 🧪 Testing in Your App
269+
270+
If you track process quality in CI:
271+
272+
```bash
273+
# Verify docs exist
32274
rake memory_bank:check
275+
276+
# Generate coverage report for tasks completeness (optional)
33277
rake memory_bank:report
34278
```
279+
280+
---
281+
282+
## 🤝 Contributing
283+
284+
1. Fork
285+
2. Create a feature branch
286+
3. Add tests
287+
4. Ensure `rspec` and `rubocop` pass
288+
5. Open a PR
289+
290+
---
291+
292+
## 📄 License
293+
294+
MIT. See `LICENSE`.
295+
296+
---
297+
298+
## 💬 Support
299+
300+
* Issues: GitHub Issues
301+
* Discussions: GitHub Discussions
302+
* Email: [[email protected]](mailto:[email protected])
303+
304+
---
305+
306+
## 🙏 Acknowledgments
307+
308+
Inspired by community work on AI agent memory systems, SPEC-driven workflows, and IDE collaboration patterns. Thanks to the Rails and broader AI developer communities for pushing the craft forward.
309+
310+
---
311+
312+
### Appendix: Example `developmentGuide.md` (Company Rails)
313+
314+
```md
315+
# Company Rails Development Guide
316+
317+
## Overview
318+
This guide documents our Rails standards and best practices.
319+
320+
## Coding Standards
321+
- Prefer service objects and form objects for complex flows
322+
- Strong Parameters; avoid mass assignment in models
323+
- RuboCop + Standard enforcement in CI
324+
325+
## Architecture Patterns
326+
- CQRS for complex read models
327+
- Background jobs for non-HTTP work
328+
- Clear boundaries for external integrations
329+
330+
## Best Practices
331+
- RSpec + FactoryBot + Faker
332+
- System specs for critical user flows
333+
- Conventional commits and trunk-based development
334+
```

0 commit comments

Comments
 (0)