Skip to content

Commit acb7317

Browse files
authored
Strengthen project-manager prompt parallel delegation emphasis (#102) (#103)
* docs(memory): implement multi-memory chunking for remory token limits (#100) - Add token limit warnings to /session-start (256 tokens = ~1,000 chars) - Replace single large workflow memory with 7 focused memories - Update memory-and-remory.md with chunking best practices - Add troubleshooting section for embedding failures - Document safe memory size: 1,200-1,500 characters per entry - Explain why --infer false doesn't affect token limits Prevents 'Failed to generate embedding' errors that blocked session initialization when storing comprehensive workflow documentation. * feat(pm): strengthen parallel delegation emphasis with decision frameworks (#102) Add 7 targeted enhancements to improve parallelization guidance: - Parallelization identification checklist with dependency test matrix - Common patterns section (5 patterns with 30-66% time savings) - Decision framework (5-step process integrated in routing) - Blocking behavior clarification (worst-case semantics) - Enhanced delegation language (strategic vs optional framing) - Example with rationale (why tasks are parallelizable) - Anti-patterns section (6 mistakes with correct approaches) Improves strength from 5/10 to 8.5/10. Prevents 50-100% time waste from missed parallelization opportunities (research+review, API+schema, multiple PR reviews). Aligns with orchestration best practices (Airflow/Kubernetes/Jenkins patterns). Adds ~135 lines total. All changes additive, backward compatible.
1 parent 77266f8 commit acb7317

3 files changed

Lines changed: 404 additions & 28 deletions

File tree

‎command/session-start.md‎

Lines changed: 80 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -187,6 +187,30 @@ Return all results in a structured format for memory storage.
187187

188188
**WAIT for @git-agent response before continuing**
189189

190+
═══════════════════════════════════════════════════════
191+
⚠️ CRITICAL: REMORY TOKEN LIMITS
192+
═══════════════════════════════════════════════════════
193+
194+
**Embedding Model Constraints:**
195+
- Model: sentence-transformers/all-MiniLM-L6-v2
196+
- Default max: 256 tokens (~1,000 characters)
197+
- Hard limit: 512 tokens (~2,000 characters)
198+
- Token ratio: ~1 token per 4 characters (English)
199+
200+
**Safe Memory Size:**
201+
- Target: 1,200-1,500 characters per memory entry
202+
- Token equivalent: 300-375 tokens (safely under limit)
203+
- Each memory must be semantically complete and independently searchable
204+
205+
**Chunking Strategy:**
206+
Store multiple focused memories instead of one large memory. Split naturally by topic:
207+
- Commit conventions
208+
- GitHub workflow
209+
- PR process
210+
- Quality gates
211+
- Testing requirements
212+
- Memory protocol
213+
190214
═══════════════════════════════════════════════════════
191215
PHASE 4: MEMORY UPDATE (MANDATORY)
192216
═══════════════════════════════════════════════════════
@@ -195,39 +219,63 @@ PHASE 4: MEMORY UPDATE (MANDATORY)
195219

196220
**Store project context using remory CLI with --infer false to preserve full detail:**
197221

222+
**Use multi-memory chunking strategy:** Store 5-7 focused memories (1,200-1,500 chars each) instead of single large memory. This prevents "Failed to generate embedding" errors from exceeding token limits.
223+
198224
```bash
199-
# Store project overview (DETAILED - preserve everything from README)
200-
remory add "Project: {name} - {full description from README including all key features}. Stack: {complete technology stack with versions}. Purpose: {main purpose and goals}. Key features: {list main features}" --user-id "$PROJECT_ID" --infer false
201-
```
202-
```bash
203-
# Store architecture insights (DETAILED - preserve all patterns and decisions)
204-
remory add "Architecture: {detailed architectural patterns from docs}. Design decisions: {all key decisions with rationale}. Components: {component structure and interactions}. Data flow: {how data flows through system}" --user-id "$PROJECT_ID" --infer false
205-
```
206-
```bash
207-
# Store current status (DETAILED - preserve activity context)
208-
remory add "Status: {X} open issues, {Y} open PRs. Recent commits: {detailed recent activity from git log including commit messages}. CI/CD: {current CI state and any issues}" --user-id "$PROJECT_ID" --infer false
209-
```
210-
```bash
211-
# Store workflow and conventions (DETAILED - preserve COMPLETE workflow information)
212-
remory add "Project workflow: {commit message format, PR process, review requirements, branch naming, communication style from CONTRIBUTING.md OR AGENTS.md - whichever exists}. Coding standards: {complete coding standards from docs}. Testing requirements: {all testing requirements including coverage targets}. Quality gates: {all quality gates that must pass}. Contribution guidelines: {all contribution rules and conventions}" --user-id "$PROJECT_ID" --infer false
225+
# Memory 1: Project Overview (Keep project basics together, ~1,200 chars max)
226+
remory add "Project: {name} - {concise description}. Stack: {technology stack with versions}. Purpose: {main purpose}. Key features: {main features list}. Architecture: {high-level patterns}. Components: {main components}." --user-id "$PROJECT_ID" --infer false
227+
228+
# Memory 2: Current Status (Project activity snapshot, ~1,000 chars max)
229+
remory add "Status: {X} open issues, {Y} open PRs. Recent commits: {recent activity from git log with commit messages}. CI/CD: {current CI state}. Active work: {current focus areas}." --user-id "$PROJECT_ID" --infer false
230+
231+
# Memory 3: Commit Conventions (If found in CONTRIBUTING.md or AGENTS.md, ~1,200-1,300 chars)
232+
remory add "Commit standards and conventions. Use Conventional Commits format: type(scope): description. Types: feat, fix, docs, style, refactor, test, chore, build, ci, perf. Include GitHub issue reference: 'feat: add auth (#123)'. Always atomic changes. Clear descriptions. Present tense, imperative mood. First line <50 chars. Examples from project docs: {examples from CONTRIBUTING/AGENTS}." --user-id "$PROJECT_ID" --infer false
233+
234+
# Memory 4: GitHub Issue Workflow (If found in CONTRIBUTING.md or AGENTS.md, ~1,200-1,300 chars)
235+
remory add "GitHub issue workflow and quality template. Every development issue requirements: {list checkboxes from docs - TDD, coverage, linting, etc.}. Validate issue content with 'gh issue view'. All work matches issue exactly. Refuse work not listed. Update issue before expanding scope. Complete only when all checkboxes done. {Additional workflow details from docs}." --user-id "$PROJECT_ID" --infer false
236+
237+
# Memory 5: PR & Review Process (If found in CONTRIBUTING.md or AGENTS.md, ~1,200-1,300 chars)
238+
remory add "Pull request and CI verification process. Feature branch workflow: {branch naming conventions from docs}. PR requirements: {title format, description requirements}. Review process: {approval requirements, self-merge policy}. CI verification: {commands used - gh run watch, monitoring requirements}. Merge strategy: {squash/merge/rebase from docs}." --user-id "$PROJECT_ID" --infer false
239+
240+
# Memory 6: Quality Gates & Testing (If found in CONTRIBUTING.md or AGENTS.md, ~1,200-1,300 chars)
241+
remory add "Quality gates and testing requirements. Zero-tolerance policy: {suppression rules from docs}. Coverage requirements: {thresholds - 80%+, per-file vs overall}. Linting: {commands and requirements}. Type checking: {requirements}. Testing approach: {TDD requirements, test patterns, mocking strategies from docs}. Local verification: {what must pass before completion}." --user-id "$PROJECT_ID" --infer false
242+
243+
# Memory 7: Communication & Philosophy (If found in CONTRIBUTING.md or AGENTS.md, ~1,200-1,300 chars)
244+
remory add "Communication style and development philosophy. Tone: {professional, concise, etc. from docs}. Minimalist principles: {LESS IS MORE, challenge necessity, etc. from docs}. Code quality: {standards from docs}. Documentation: {when to create, approval requirements}." --user-id "$PROJECT_ID" --infer false
213245
```
214246

215247
**CRITICAL:** Use `--infer false` to preserve FULL TEXT without LLM extraction/shortening.
216248

217-
**What to store (be COMPREHENSIVE):**
218-
- Project overview: name, complete description, full technology stack with versions, purpose, key features
219-
- **Workflow (CRITICAL)**: commit message format, PR process, review requirements, branch naming, communication style from CONTRIBUTING.md or AGENTS.md (whichever exists)
220-
- Architecture: all patterns, all design decisions with rationale, component structure, data flow
221-
- Current status: open issues, PRs, detailed recent commits, CI/CD state
222-
- Conventions: complete coding standards, all testing requirements, all quality gates
223-
- Recent learnings: detailed solutions found, patterns discovered, decisions made with context
224-
- **Everything important for future sessions** - be thorough, not summary!
249+
**Store comprehensive context using MULTIPLE focused memories (1,200-1,500 chars each):**
250+
251+
**Core Project Info (2 memories):**
252+
- Memory 1: Project overview - name, description, stack, purpose, architecture, components
253+
- Memory 2: Current status - open issues, PRs, recent commits, CI/CD state, active work
254+
255+
**Workflow Documentation (5-6 memories from CONTRIBUTING.md or AGENTS.md):**
256+
- Memory 3: Commit conventions - format, types, examples, issue references
257+
- Memory 4: GitHub issue workflow - quality template, checkboxes, scope control
258+
- Memory 5: PR & review process - branch naming, PR requirements, CI verification
259+
- Memory 6: Quality gates & testing - coverage, linting, TDD, local verification
260+
- Memory 7: Communication & philosophy - tone, minimalist principles, standards
261+
262+
**Chunking Guidelines:**
263+
- Each memory: 1,200-1,500 characters (safely under 256-token embedding limit)
264+
- Semantically complete: Each memory understandable independently
265+
- Topic-focused: One coherent concept per memory
266+
- Searchable: Use clear topic names for future retrieval
267+
- Natural boundaries: Split at logical sections, not mid-paragraph
268+
269+
**Why Chunking:**
270+
Remory's embedding model (sentence-transformers/all-MiniLM-L6-v2) has 256-token default limit (~1,000 chars). Long texts (2,500+ chars) fail with "Failed to generate embedding" errors. Multiple focused memories succeed where single large memory fails.
225271

226272
**Why this matters:**
227-
- Future sessions get FULL context immediately, not extracted facts
228-
- Prevents repeating research and discovery
229-
- Builds institutional knowledge across sessions with full detail
230-
- Enables continuity and consistency
273+
- ✅ Each memory successfully embeds (under token limits)
274+
- ✅ Semantically searchable across separate memories
275+
- ✅ Future agents find relevant concepts easily
276+
- ✅ Easier to update individual topics
277+
- ✅ Reduces cognitive load (focused topics vs sprawling docs)
278+
- ✅ Prevents embedding failures that block session initialization
231279

232280
═══════════════════════════════════════════════════════
233281
PHASE 5: SUCCESS VERIFICATION & SUMMARY
@@ -285,6 +333,9 @@ CRITICAL RULES
285333
- Search memory FIRST with specific semantic queries
286334
- Store ALL gathered context with `--infer false` to preserve full detail
287335
- Use detailed, comprehensive descriptions (not summaries)
336+
- Split large memories into focused chunks (1,200-1,500 chars each)
337+
- Verify each memory is semantically complete and independently searchable
338+
- Use natural topic boundaries (commit conventions, PR process, quality gates)
288339
- Update TodoWrite after each phase
289340
- Keep user summary brief and actionable
290341

@@ -298,6 +349,9 @@ CRITICAL RULES
298349
- Assume documentation structure - adapt to what the project actually has
299350
- Skip files that don't exist - read what's there, not what you expect
300351
- Skip memory storage - it's MANDATORY for session continuity
352+
- Store memories exceeding 1,500 characters (risk embedding failure)
353+
- Create single large "Project workflow" memory (will fail at 2,500+ chars)
354+
- Split mid-paragraph or mid-sentence (breaks semantic coherence)
301355

302356
═══════════════════════════════════════════════════════
303357

‎instructions/memory-and-remory.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,15 @@ remory list --user-id "$(cat .project-id 2>/dev/null || (uuidgen | tee .project-
101101
- Things to avoid (anti-patterns)
102102
- Integration patterns with other components
103103

104+
**Length Considerations:**
105+
If your memory content exceeds 1,500 characters, split into multiple focused memories:
106+
- One memory for architecture decisions
107+
- One memory for solutions to specific problem types
108+
- One memory for testing/linting configuration
109+
- One memory for anti-patterns and things to avoid
110+
111+
Each memory should be independently searchable and semantically complete.
112+
104113
### Natural Language Format
105114
No entity types or structured data needed. Just plain text:
106115
- "Decision: Using PostgreSQL because ACID + JSON support needed"
@@ -118,6 +127,57 @@ The `--infer false` flag disables auto-consolidation. When enabled, Remory's LLM
118127
- `OPENAI_API_KEY`: For LLM consolidation (optional, recommended)
119128
- `remory` CLI in PATH
120129

130+
### ⚠️ CRITICAL: Token Limits and Memory Size Constraints
131+
132+
**Embedding Model Specifications:**
133+
- **Model:** sentence-transformers/all-MiniLM-L6-v2
134+
- **Default max:** 256 tokens (~1,000 characters for English text)
135+
- **Hard architectural limit:** 512 tokens (~2,000 characters)
136+
- **Token-to-character ratio:** Approximately 1 token per 4 characters (English)
137+
138+
**Safe Memory Size Guidelines:**
139+
- **Target:** 1,200-1,500 characters per `remory add` command
140+
- **Token equivalent:** 300-375 tokens (safely under 256-token default with margin)
141+
- **Maximum:** Do NOT exceed 1,500 characters in a single memory entry
142+
- **Consequence of violation:** "Failed to generate embedding" error
143+
144+
**Why `--infer false` Doesn't Help:**
145+
The `--infer false` flag disables LLM-powered consolidation (happens AFTER embedding). Token limits are enforced DURING embedding (BEFORE consolidation). If embedding fails due to length, consolidation never runs.
146+
147+
**Chunking Strategy (Required for Long Content):**
148+
149+
When storing comprehensive information that exceeds 1,500 characters:
150+
151+
1. **Split into focused topic-based memories** instead of one large memory
152+
2. **Each memory must be semantically complete** (independently understandable)
153+
3. **Use natural boundaries:** Split at logical sections, not mid-paragraph
154+
4. **Topic naming:** Use clear, searchable topic names
155+
156+
**Example - WRONG (Will Fail):**
157+
```bash
158+
# Single memory with 2,500+ characters - FAILS with "Failed to generate embedding"
159+
remory add "Project workflow: commit conventions, PR process, quality gates, testing requirements, communication style, minimalist philosophy, [continues for 2,500 chars]..." --user-id "$PROJECT_ID" --infer false
160+
```
161+
162+
**Example - CORRECT (Will Succeed):**
163+
```bash
164+
# Memory 1: Commit conventions (~1,200 chars)
165+
remory add "Commit standards and conventions. Use Conventional Commits format: type(scope): description. Types: feat, fix, docs, refactor, test. Include issue reference. Examples: 'feat: add auth (#123)'. Present tense, imperative mood. First line <50 chars." --user-id "$(cat .project-id 2>/dev/null || (uuidgen | tee .project-id))" --infer false
166+
167+
# Memory 2: PR process (~1,300 chars)
168+
remory add "Pull request workflow. Feature branch naming: feature/123-description. PR requirements: title format, description, CI green. Review process: mandatory approval, no self-merge. Merge strategy: squash. CI monitoring: gh run watch for real-time." --user-id "$(cat .project-id 2>/dev/null || (uuidgen | tee .project-id))" --infer false
169+
170+
# Memory 3: Quality gates (~1,200 chars)
171+
remory add "Zero-tolerance quality enforcement. Never suppress linting (no # noqa, # type: ignore). Coverage: 80%+ per file, CI enforces. Testing: TDD required, tests before implementation. Local verification: run all tests, all linting, type checking before completion." --user-id "$(cat .project-id 2>/dev/null || (uuidgen | tee .project-id))" --infer false
172+
```
173+
174+
**Benefits of Multi-Memory Approach:**
175+
- ✅ Each memory successfully embeds (under token limits)
176+
- ✅ Semantically searchable across separate memories
177+
- ✅ Easier to update individual topics without affecting others
178+
- ✅ Future agents can search specific topics and get focused results
179+
- ✅ Reduces cognitive load (focused topics vs sprawling documents)
180+
121181
---
122182

123183
## Part 3: Project-Scoped Memory Architecture
@@ -165,6 +225,13 @@ Leverage Remory's advanced features:
165225
- Quality gate results and trends
166226
- Project-wide architectural decisions
167227

228+
**⚠️ Length Management:**
229+
When storing delegation history or multi-agent coordination patterns:
230+
- If content exceeds 1,500 characters, split into multiple memories
231+
- Example: One memory for Phase 1 delegation patterns, another for Phase 2
232+
- Each memory should cover a coherent delegation scenario or pattern
233+
- Never create single memory exceeding 1,500 characters
234+
168235
### Specialist Agents (All Subagents)
169236

170237
**SEARCH FOR:**
@@ -214,6 +281,47 @@ remory add "..." --user-id "$(cat .project-id 2>/dev/null || (uuidgen | tee .pro
214281
- Check .project-id matches previous sessions
215282
- Use `remory list` to browse all memories
216283

284+
### Memory Too Long - Embedding Failures
285+
286+
**Problem:** `remory add` fails with "Failed to generate embedding" error
287+
288+
**Root Cause:** Text exceeds embedding model token limits
289+
- Default limit: 256 tokens (~1,000 characters)
290+
- Your text: Likely 2,000+ characters (~500+ tokens)
291+
292+
**Solution: Chunk Your Memory**
293+
294+
1. **Measure your content:** Count characters (not words)
295+
2. **If > 1,500 characters:** Split into multiple memories
296+
3. **Use topic-based splitting:**
297+
- Commit conventions
298+
- PR workflow
299+
- Quality gates
300+
- Testing requirements
301+
4. **Each chunk:** 1,200-1,500 characters, semantically complete
302+
5. **Test:** Run `remory add` for each chunk separately
303+
304+
**Example Split:**
305+
```bash
306+
# BEFORE (fails at 2,500 chars)
307+
remory add "Huge text block..." --user-id "$(cat .project-id 2>/dev/null || (uuidgen | tee .project-id))" --infer false
308+
309+
# AFTER (succeeds - 3 chunks at ~1,200 chars each)
310+
remory add "Commit conventions: [1,200 chars]..." --user-id "$(cat .project-id 2>/dev/null || (uuidgen | tee .project-id))" --infer false
311+
remory add "PR workflow: [1,200 chars]..." --user-id "$(cat .project-id 2>/dev/null || (uuidgen | tee .project-id))" --infer false
312+
remory add "Quality gates: [1,100 chars]..." --user-id "$(cat .project-id 2>/dev/null || (uuidgen | tee .project-id))" --infer false
313+
```
314+
315+
**Verification:**
316+
After chunking, search to verify all memories were stored:
317+
```bash
318+
remory search "commit conventions" --user-id "$(cat .project-id 2>/dev/null || (uuidgen | tee .project-id))" --limit 3
319+
remory search "PR workflow" --user-id "$(cat .project-id 2>/dev/null || (uuidgen | tee .project-id))" --limit 3
320+
remory search "quality gates" --user-id "$(cat .project-id 2>/dev/null || (uuidgen | tee .project-id))" --limit 3
321+
```
322+
323+
All searches should return relevant results.
324+
217325
---
218326

219327
## Part 6: Compliance Verification

0 commit comments

Comments
 (0)