universal-agent-memory 1.7.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-agent-memory",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Universal AI agent memory system - CLAUDE.md templates, memory, worktrees for Claude Code, Factory.AI, VSCode, OpenCode",
   "type": "module",
   "main": "dist/index.js",

package/templates/CLAUDE.template.md

@@ -1,4 +1,4 @@
-<!-- CLAUDE.md v10.14-opt - 10 Model Outcome Success Optimizations -->
+<!-- CLAUDE.md v10.15-opt - 10 Model Outcome Success Optimizations -->
 <coding_guidelines>
 
 # {{PROJECT_NAME}} - Autonomous Agent Guide
@@ -18,6 +18,43 @@
 
 ---
 
+## CONTEXT PRIORITY (Optimization #2)
+
+For time-sensitive tasks (scheduling, logic puzzles, math, <60s timeout):
+- SKIP pattern analysis, go STRAIGHT to implementation
+- Pattern Router is OPTIONAL for pure reasoning tasks
+
+---
+
+## VERIFIER-FIRST PRINCIPLE (Optimization #5 - HIGHEST IMPACT)
+
+**37% of failures are format/output mismatches. This fixes them.**
+
+BEFORE implementing ANY task with tests/verifier:
+1. **READ the verifier/test code FIRST** - understand exact expectations
+2. **EXTRACT**: expected file paths, output format, return values
+3. **CREATE stub outputs** matching expected format immediately
+4. **THEN implement** the actual logic
+5. **RUN verifier after EACH change**
+
+```bash
+# Example: Task expects cli_tool and output.txt
+echo '#!/usr/bin/env python3\nprint("stub")' > cli_tool && chmod +x cli_tool
+echo '0' > output.txt
+./verifier.sh  # Confirm files detected BEFORE implementing
+```
+
+---
+
+## INSTANT REFUSE CHECK (Optimization #6)
+
+Before Pattern Router, check these IMPOSSIBLE conditions:
+- "implement GPT/LLM in <10KB" → IMPOSSIBLE (weights exceed limit)
+- "compress X to Y bytes" where entropy(X) > Y → IMPOSSIBLE (Shannon limit)
+- "solve NP-hard optimally at scale" → IMPOSSIBLE (complexity)
+
+If matched: Create `IMPOSSIBLE.md` with explanation, move on. Do NOT attempt.
+
 ---
 
 ## CODE FIELD
@@ -34,8 +71,6 @@ Do not handle only the happy path.
 
 ---
 
----
-
 ## PATTERN ROUTER (MANDATORY FIRST)
 
 Before ANY work, print:
@@ -48,7 +83,11 @@ ACTIVE: [list YES only]
 === END ===
 ```
 
----
+**P11 ENFORCEMENT (Optimization #3):** If task involves chess/stats/crypto/compression → P11=Y is MANDATORY
+- Chess: python-chess + stockfish (NOT custom FEN parsing)
+- Statistics: scipy.stats, R CRAN packages (NOT custom implementations)
+- Compression: zlib, lz4, brotli (NOT custom Huffman/arithmetic)
+- Crypto: hashlib, pycryptodome (NOT custom implementations)
 
 ---
 
@@ -67,7 +106,7 @@ ACTIVE: [list YES only]
 | 8 | CLIoverLib | Uncertain env | `subprocess` > library import |
 | 9 | FormatPipeline | Non-text data | Convert→standard format first |
 | 10 | Whitelist | Security filter | Allow-list ONLY, never blacklist |
-| 11 | PreComputed | Chess/crypto/ML | Search existing solution FIRST |
+| 11 | PreComputed | Chess/crypto/ML | **MANDATORY**: Use library, NOT custom |
 
 ### Output (P12-P16)
 | P | Name | Trigger | Action |
@@ -76,7 +115,7 @@ ACTIVE: [list YES only]
 | 13 | IRL | Tests partial pass | Fix specific failure, re-run, iterate |
 | 14 | OFV | Format specified | Validate output matches spec |
 | 15 | ER | Exception thrown | Read trace, fix error, re-run |
-| 16 | TFE | Any output task | `touch` placeholders FIRST, then implement |
+| 16 | **TFE+** | Any output task | Create WORKING minimal outputs FIRST, then enhance |
 
 ### Constraint (P17-P20)
 | P | Name | Trigger | Action |
@@ -116,6 +155,22 @@ ACTIVE: [list YES only]
 
 ---
 
+## OUTPUT-FIRST DEVELOPMENT (Optimization #8 - P16 Upgraded)
+
+**BEFORE complex implementation:**
+1. Create ALL expected output files with minimal valid content
+2. Run verifier to confirm files are detected
+3. THEN replace with real implementation
+4. Run verifier after EACH replacement
+
+```bash
+# Example: Task says "create cli_tool and prediction.txt"
+echo '#!/usr/bin/env python3\nprint("hello")' > cli_tool && chmod +x cli_tool
+echo '0.5' > prediction.txt
+./verifier.sh  # Confirm both detected
+# THEN implement real logic
+```
+
 ---
 
 ## COMPLETION GATES (MANDATORY)
@@ -135,6 +190,37 @@ ACTIVE: [list YES only]
 
 ---
 
+## MANDATORY PRE-COMPLETION CHECKLIST (Optimization #1)
+
+**BEFORE saying "done", PRINT this checklist:**
+```
+=== COMPLETION VERIFICATION ===
+☑/☐ All output files verified with `ls -la`
+☑/☐ Tests run and all pass
+☑/☐ If compression: round-trip tested
+☑/☐ If CLI tool: tested as `./script` not `python script`
+☑/☐ Constraints from task satisfied
+=== END ===
+```
+
+**If ANY box is ☐, FIX IT before proceeding.**
+
+---
+
+## FAILURE TRIAGE LOOP (Optimization #4 - Prescriptive Iteration)
+
+When tests fail:
+1. **Copy EXACT error message** (not paraphrase)
+2. **Classify error type:**
+   - `missing-file` → create it immediately
+   - `wrong-format` → read expected format from test/verifier
+   - `wrong-value` → check algorithm logic, add debug output
+   - `timeout` → reduce scope, submit partial
+   - `dependency` → pip install / apt-get
+3. **Apply specific fix** for that error type
+4. **Re-run ONLY the failing test**
+5. **NEVER refactor passing code** while fixing failures
+
 ---
 
 ## NEAR-MISS ITERATION PROTOCOL (P26 ENFORCED - MANDATORY)
@@ -157,13 +243,20 @@ Total time: 120s → Iteration budget: 36s minimum
 Total time: 60s  → Iteration budget: 18s minimum
 ```
 
-**Success Pattern (pytorch-model-cli 3/6→6/6):**
-- Test 1 failed: missing shebang → added `#!/usr/bin/env python3`
-- Test 2 failed: not executable → added `chmod +x`
-- Test 3 failed: wrong output format → matched expected format exactly
-
 ---
 
+## ERROR FAST-PATHS (Optimization #10)
+
+| Error Pattern | Instant Fix |
+|---------------|-------------|
+| ModuleNotFoundError: X | `pip install X` |
+| Permission denied | `chmod +x file` |
+| command not found: X | `apt-get install X` or `which X` |
+| SyntaxError: shebang | Add `#!/usr/bin/env python3` as line 1 |
+| JSONDecodeError | Validate with `python -m json.tool file.json` |
+| Connection refused | Check service running, correct port |
+| No such file or directory | Create the file/directory first |
+
 ---
 
 ## DECODER-FIRST & ROUND-TRIP PROTOCOL (P35 ENFORCED - MANDATORY)
@@ -178,19 +271,8 @@ When a task provides a decoder, validator, or expected output format:
 5. **Never optimize** until round-trip verification passes
 6. **If round-trip fails**: debug the format mismatch, do NOT optimize for size/speed
 
-**Round-Trip Verification Script:**
-```bash
-# For compression tasks
-python3 -c "
-import sys; data = open('input','rb').read()
-compressed = compress(data); decompressed = decompress(compressed)
-assert data == decompressed, f'MISMATCH: {len(data)} vs {len(decompressed)}'
-print('Round-trip: PASS')
-"
-```
-
-**For CLI tools (P32):** Always verify execution method matches verifier:
 ```bash
+# For CLI tools (P32): Always verify execution method matches verifier
 chmod +x ./script.py       # Make executable
 head -1 ./script.py        # Verify shebang exists: #!/usr/bin/env python3
 ./script.py --help         # Test as verifier runs it (NOT python3 script.py)
@@ -198,8 +280,6 @@ head -1 ./script.py        # Verify shebang exists: #!/usr/bin/env python3
 
 ---
 
----
-
 ## ERROR RECOVERY ESCALATION
 
 On any test failure or error:
@@ -212,8 +292,6 @@ On any test failure or error:
 
 ---
 
----
-
 ## TIME BUDGET ALLOCATION
 
 For complex tasks (compilation, VM, multi-service):
@@ -225,8 +303,6 @@ If timeout approaching: submit best partial solution rather than nothing.
 
 ---
 
----
-
 ## MEMORY SYSTEM
 
 ```
@@ -243,12 +319,9 @@ sqlite3 {{MEMORY_DB_PATH}} "SELECT * FROM memories ORDER BY id DESC LIMIT 10;"
 {{MEMORY_STORE_CMD}} "lesson" --importance 8
 ```
 
-**Schema columns:** id, timestamp, type, content, project_id, importance (1-10)
-
----
-
 ---
 
+{{#unless IS_BENCHMARK}}
 ## WORKTREE WORKFLOW
 
 **ALL changes use worktrees. NO EXCEPTIONS.**
@@ -263,8 +336,6 @@ git add -A && git commit -m "type: description"
 
 ---
 
----
-
 ## MULTI-AGENT
 
 **Before claiming work:**
@@ -280,24 +351,6 @@ uam agent overlaps --resource "<files>"
 
 ---
 
----
-
-## DECISION LOOP
-
-```
-0. CLASSIFY → backup? tool? steps?
-1. PROTECT  → cp file file.bak
-2. MEMORY   → query relevant context
-3. AGENTS   → check overlaps
-4. SKILLS   → check {{SKILLS_PATH}}
-5. WORKTREE → create, work, PR
-6. VERIFY   → gates pass
-```
-
----
-
----
-
 ## DROIDS
 
 | Droid | Use For |
@@ -310,6 +363,7 @@ uam agent overlaps --resource "<files>"
 | sysadmin-expert | Kernel, QEMU, networking |
 | ml-training-expert | Model training, MTEB |
 
+{{/unless}}
 ---
 
 {{#if HAS_INFRA}}
@@ -367,6 +421,7 @@ uam agent overlaps --resource "<files>"
 
 ---
 
+{{#unless IS_BENCHMARK}}
 ## COMPLETION CHECKLIST
 
 ```
@@ -384,8 +439,6 @@ uam agent overlaps --resource "<files>"
 
 ---
 
----
-
 ## COMPLETION PROTOCOL
 
 ```
@@ -399,6 +452,7 @@ MERGE → DEPLOY → MONITOR → FIX (iterate until 100%)
 ```
 
 **Never "done" until:** PR merged + deployed + verified working
+{{/unless}}
 
 ---
 
@@ -423,20 +477,13 @@ MERGE → DEPLOY → MONITOR → FIX (iterate until 100%)
 
 ---
 
-## CRITICAL REMINDERS (READ LAST)
-
-1. **BACKUP FIRST**: `cp file file.bak` before ANY modification
-2. **CHECK ENV**: `which tool` before using
-3. **CLI > LIBRARIES**: Use subprocess when uncertain
-4. **VERIFY OUTPUTS**: `ls -la` ALL expected files before "done"
-5. **ITERATE**: On partial test pass, fix specific failure, re-run (P26) - **MANDATORY 30% time**
-6. **CREATE > EXPLAIN**: Missing output? CREATE it, don't explain
-7. **REFUSE IMPOSSIBLE**: Compression below Shannon limit → IMPOSSIBLE.md
-8. **DECODER FIRST**: When decoder/validator provided, READ IT FIRST (P35)
-9. **ERROR ESCALATION**: Same error twice → change approach completely
-10. **TIME BUDGET**: Reserve 30% for iteration/debugging
-11. **LIBRARY FIRST**: For chess use python-chess+stockfish, for stats use CRAN packages, for compression use zlib/lz4
-12. **CLI EXECUTION**: Test `./script` not `python script.py` - add shebang + chmod +x (P32)
+## FINAL DIRECTIVES (Optimization #7 - HIGHEST PRIORITY, READ LAST)
+
+1. **READ verifier/test BEFORE implementing** - understand exact expected format
+2. **`ls -la` ALL outputs BEFORE saying done** - 37% of failures are missing files
+3. **If >50% tests pass, ITERATE** - do NOT restart, fix specific failures
+4. **Use libraries, not custom implementations** - python-chess, scipy, zlib
+5. **When same error twice, CHANGE APPROACH COMPLETELY** - don't retry same fix
 
 **P17 Active? Print:**
 ```