universal-agent-memory 0.5.3 → 0.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-agent-memory",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "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,12 +1,12 @@
 <!--
-  CLAUDE.md Universal Template - v8.0
+  CLAUDE.md Universal Template - v9.0
   
   CHANGES IN THIS VERSION:
-  - Context Field integration (code field + inhibition-style directives)
-  - Inhibition > Instruction: "Do not X" creates blockers, "Do X" creates preferences
-  - 4-line code field for 100% assumption stating, 89% bug detection
-  - Simplified setup (auto-works, no clicking required)
-  - Database protection (never delete existing data)
+  - Fully universal with Handlebars placeholders (no hardcoded project content)
+  - Context Field integration with Code Field prompt
+  - Inhibition-style directives ("Do not X" creates blockers)
+  - Optimized token usage with conditional sections
+  - Database protection (memory persists with project)
   
   CODE FIELD ATTRIBUTION:
   The Code Field prompt technique is based on research from:
@@ -37,15 +37,15 @@
     {{DOCKER_COMPOSE_PATH}}
   
   Commands:
-    {{TEST_COMMAND}}, {{BUILD_COMMAND}}, {{LINT_COMMAND}}, {{INSTALL_HOOKS_CMD}}
+    {{TEST_COMMAND}}, {{BUILD_COMMAND}}, {{LINT_COMMAND}}
 -->
 
 <coding_guidelines>
 
 # {{PROJECT_NAME}} - Autonomous Agent Guide
 
-{{#if ISSUE_TRACKER}}
-> {{{ISSUE_TRACKER}}}
+{{#if DESCRIPTION}}
+> {{DESCRIPTION}}
 {{/if}}
 
 ---
@@ -63,9 +63,11 @@
 
 ---
 
-## 🔒 CODE FIELD - MANDATORY FOR ALL CODE
+## 🧬 CODE FIELD - COGNITIVE ENVIRONMENT
 
-**Before writing ANY code, apply these constraints:**
+**Apply to ALL code generation. Creates conditions where better code emerges naturally.**
+
+### Core Inhibitions
 
 ```
 Do not write code before stating assumptions.
@@ -74,25 +76,29 @@ Do not handle only the happy path.
 Under what conditions does this work?
 ```
 
-### Code Generation Protocol
+### Before Writing Code
+
+- What are you assuming about the input?
+- What are you assuming about the environment?
+- What would break this?
+- What would a malicious caller do?
+
+### Do Not
 
-**BEFORE CODE** (required):
-- State assumptions about input, environment, dependencies
-- Enumerate edge cases and failure modes
-- Define explicit scope ("This handles X, not Y")
-- Ask: "What would break this? What would a malicious caller do?"
+- Write code before stating assumptions
+- Claim correctness you haven't verified
+- Handle the happy path and gesture at the rest
+- Import complexity you don't need
+- Solve problems you weren't asked to solve
+- Produce code you wouldn't want to debug at 3am
 
-**IN CODE**:
-- Comments explain *why*, not *what*
-- Edge cases handled OR explicitly rejected with clear errors
-- Error paths as considered as happy paths
-- Smaller than your first instinct
+### Expected Output Format
 
-**AFTER CODE** (required):
-- "What this handles" section
-- "What this does NOT handle" section
-- Known limitations documented
-- Conditions for correctness stated
+**Before code**: Assumptions stated explicitly, scope bounded
+**In code**: Smaller than expected, edge cases handled or explicitly rejected
+**After code**: "What this handles" and "What this does NOT handle" sections
+
+*Attribution: Based on [context-field research](https://github.com/NeoVertex1/context-field)*
 
 ---
 
@@ -102,7 +108,8 @@ Under what conditions does this work?
 
 ```bash
 uam task ready                                    # Check existing work
-uam memory query "recent context"                 # Check memory for context
+sqlite3 {{MEMORY_DB_PATH}} "SELECT * FROM memories ORDER BY id DESC LIMIT 10;"
+sqlite3 {{MEMORY_DB_PATH}} "SELECT * FROM session_memories WHERE session_id='current' ORDER BY id DESC LIMIT 5;"
 uam agent status                                  # Check other active agents
 ```
 
@@ -110,22 +117,6 @@ uam agent status                                  # Check other active agents
 
 ---
 
-## 🛑 CRITICAL INHIBITIONS
-
-**These are BLOCKERS, not suggestions. Do not proceed without satisfying them.**
-
-| Inhibition | Rationale |
-|------------|-----------|
-| Do not begin work without querying memory | Context prevents duplicate work |
-| Do not commit to {{DEFAULT_BRANCH}} | All changes require worktree + PR |
-| Do not claim work without overlap check | Prevents merge conflicts |
-| Do not create PR with failing tests | Broken code must not merge |
-| Do not complete task without storing learnings | Memory enables endless context |
-| Do not write code without stating assumptions | Prevents hidden bugs |
-| Do not handle only the happy path | Edge cases are where bugs live |
-
----
-
 ## 🤖 MULTI-AGENT COORDINATION PROTOCOL
 
 ### Before Claiming Any Work
@@ -160,9 +151,20 @@ uam agent announce \
 | `high` | Wait or split work | Same file, different sections |
 | `critical` | STOP - request handoff | Same file, same sections |
 
-### Agent Capability Routing
+### Parallel Work Patterns
+
+```bash
+# CORRECT: Independent droids can run in parallel
+Task(subagent_type: "code-quality-guardian", ...) 
+Task(subagent_type: "security-auditor", ...)      # Runs concurrently
+Task(subagent_type: "performance-optimizer", ...) # Runs concurrently
+
+# CORRECT: Coordinate merge order for overlapping changes
+# Agent A finishes first → merges first
+# Agent B rebases → merges second
+```
 
-Route tasks to specialized droids for optimal results:
+### Agent Capability Routing
 
 | Task Type | Route To | Capabilities |
 |-----------|----------|--------------|
@@ -173,8 +175,6 @@ Route tasks to specialized droids for optimal results:
 | Documentation | `documentation-expert` | jsdoc, readme, api-docs |
 | Code quality | `code-quality-guardian` | complexity, naming, solid |
 
-**Missing expert?** Generate one: `uam droids add <name> --capabilities "..." --triggers "..."`
-
 ---
 
 ## 📋 MANDATORY DECISION LOOP
@@ -184,75 +184,87 @@ Route tasks to specialized droids for optimal results:
 │                    EXECUTE FOR EVERY TASK                        │
 ├─────────────────────────────────────────────────────────────────┤
 │                                                                  │
-│  1. MEMORY   │ Do not begin without: uam memory query "<keywords>"│
-│              │ Check for relevant past context                   │
+│  1. MEMORY   │ sqlite3 {{MEMORY_DB_PATH}} "...LIMIT 20"         │
+│              │ {{MEMORY_QUERY_CMD}} "<keywords>"                 │
+│              │ Check session_memories for current context        │
 │                                                                  │
-│  2. AGENTS   │ Do not claim without: uam agent overlaps          │
+│  2. AGENTS   │ uam agent overlaps --resource "<files>"          │
 │              │ If overlap: coordinate or wait                    │
 │                                                                  │
 │  3. SKILLS   │ Check {{SKILLS_PATH}} for applicable skill        │
-│              │ Missing skill? Generate: uam droids add           │
 │              │ Invoke BEFORE implementing                        │
 │                                                                  │
-│  4. WORKTREE │ Do not commit to {{DEFAULT_BRANCH}}               │
-│              │ {{WORKTREE_CREATE_CMD}} <slug>                    │
-│              │ cd {{WORKTREE_DIR}}/NNN-<slug>/                   │
+│  4. WORKTREE │ {{WORKTREE_CREATE_CMD}} <slug>                   │
+│              │ cd {{WORKTREE_DIR}}/NNN-<slug>/                  │
+│              │ NEVER commit to {{DEFAULT_BRANCH}}               │
 │                                                                  │
-│  5. CODE     │ Apply CODE FIELD constraints (above)              │
-│              │ State assumptions → Implement → Test              │
+│  5. WORK     │ Implement → Test → {{WORKTREE_PR_CMD}}           │
 │                                                                  │
-│  6. PR       │ Do not merge with failing tests                   │
-│              │ {{WORKTREE_PR_CMD}} → parallel reviews            │
+│  6. MEMORY   │ Update short-term after actions                   │
+│              │ Update session_memories for decisions             │
+│              │ Store lessons in long-term (importance 7+)        │
 │                                                                  │
-│  7. MEMORY   │ Do not complete without storing learnings         │
-│              │ uam memory store "lesson" --importance 7+         │
+│  7. VERIFY   │ ☐ Memory ☐ Worktree ☐ PR ☐ Skills ☐ Agents      │
 │                                                                  │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
 ---
 
-## 🧠 ENDLESS CONTEXT - PROJECT MEMORY SYSTEM
-
-**Your context is NOT limited to this conversation.**
-
-Memory persists with the project, enabling:
-- Recall of decisions from weeks/months ago
-- Learning from past mistakes (gotchas)
-- Understanding of why code is the way it is
-- Handoff between sessions without information loss
+## 🧠 FOUR-LAYER MEMORY SYSTEM
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
-│  L1: WORKING      │ Recent actions       │ {{SHORT_TERM_LIMIT}} max │ SQLite       │
-│  L2: SESSION      │ Current session      │ Per session              │ SQLite       │
-│  L3: SEMANTIC     │ Long-term learnings  │ {{LONG_TERM_BACKEND}}    │ Vector search│
-│  L4: KNOWLEDGE    │ Entity relationships │ SQLite                   │ Graph        │
+│  L1: WORKING      │ SQLite memories     │ {{SHORT_TERM_LIMIT}} max │ <1ms   │
+│  L2: SESSION      │ SQLite session_mem  │ Current session      │ <5ms   │
+│  L3: SEMANTIC     │ {{LONG_TERM_BACKEND}}│ Vector search        │ ~50ms  │
+│  L4: KNOWLEDGE    │ SQLite entities     │ Graph relationships  │ <20ms  │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
-### When to Store Memories
+### Layer Selection
 
-| Situation | Action |
-|-----------|--------|
-| Learned something reusable | `uam memory store "lesson" --importance 8` |
-| Fixed a tricky bug | `uam memory store "bug fix" --tags bug-fix --importance 7` |
-| Discovered a gotcha | `uam memory store "gotcha" --tags gotcha --importance 9` |
-| Made architectural decision | `uam memory store "decision: X because Y" --importance 8` |
+| Question | YES → Layer |
+|----------|-------------|
+| Just did this (last few minutes)? | L1: Working |
+| Session-specific decision/context? | L2: Session |
+| Reusable learning for future? | L3: Semantic |
+| Entity relationships? | L4: Knowledge Graph |
 
-### When to Query Memories
+### Memory Commands
 
-| Situation | Action |
-|-----------|--------|
-| Starting ANY new work | `uam memory query "relevant keywords"` |
-| Debugging unfamiliar code | `uam memory query "similar error"` |
-| Understanding past decisions | `uam memory query "why we did X"` |
+```bash
+# L1: Working Memory
+sqlite3 {{MEMORY_DB_PATH}} "INSERT INTO memories (timestamp,type,content) VALUES (datetime('now'),'action','...');"
+
+# L2: Session Memory
+sqlite3 {{MEMORY_DB_PATH}} "INSERT INTO session_memories (session_id,timestamp,type,content,importance) VALUES ('current',datetime('now'),'decision','...',7);"
+
+# L3: Semantic Memory  
+{{MEMORY_STORE_CMD}} lesson "..." --tags t1,t2 --importance 8
+
+# L4: Knowledge Graph
+sqlite3 {{MEMORY_DB_PATH}} "INSERT INTO entities (type,name,first_seen,last_seen,mention_count) VALUES ('file','x.ts',datetime('now'),datetime('now'),1);"
+sqlite3 {{MEMORY_DB_PATH}} "INSERT INTO relationships (source_id,target_id,relation,timestamp) VALUES (1,2,'depends_on',datetime('now'));"
+```
+
+### Consolidation Rules
+
+- **Trigger**: Every 10 working memory entries
+- **Action**: Summarize → session_memories, Extract lessons → semantic memory
+- **Dedup**: Skip if content_hash exists OR similarity > 0.92
+
+### Decay Formula
+
+```
+effective_importance = importance × (0.95 ^ days_since_access)
+```
 
 ---
 
 ## 🌳 WORKTREE WORKFLOW
 
-**Do not commit to {{DEFAULT_BRANCH}}. NO EXCEPTIONS.**
+**ALL code changes use worktrees. NO EXCEPTIONS.**
 
 ```bash
 # Create
@@ -309,7 +321,7 @@ Task(subagent_type: "documentation-expert", prompt: "Check: <files>")
 | feature request | `uam task create --type feature` |
 | code file for editing | check overlaps → skills → worktree |
 | review/check/look | query memory first |
-| ANY code change | apply CODE FIELD, tests required |
+| ANY code change | tests required |
 
 ---
 
@@ -327,32 +339,20 @@ Task(subagent_type: "documentation-expert", prompt: "Check: <files>")
 
 {{{ARCHITECTURE_OVERVIEW}}}
 
----
 {{/if}}
-
 {{#if CORE_COMPONENTS}}
 ## 🔧 Components
 
 {{{CORE_COMPONENTS}}}
 
----
 {{/if}}
-
-{{#if DATABASE_ARCHITECTURE}}
-## 🗄️ Database
-
-{{{DATABASE_ARCHITECTURE}}}
-
----
-{{/if}}
-
 {{#if AUTH_FLOW}}
 ## 🔐 Authentication
 
 {{{AUTH_FLOW}}}
 
----
 {{/if}}
+---
 
 ## 📋 Quick Reference
 
@@ -361,33 +361,27 @@ Task(subagent_type: "documentation-expert", prompt: "Check: <files>")
 ```bash
 {{{CLUSTER_CONTEXTS}}}
 ```
+
 {{/if}}
+{{#if PROJECT_URLS}}
+### URLs
+{{{PROJECT_URLS}}}
 
+{{/if}}
 {{#if KEY_WORKFLOWS}}
 ### Workflows
 ```
 {{{KEY_WORKFLOWS}}}
 ```
-{{/if}}
 
+{{/if}}
+{{#if ESSENTIAL_COMMANDS}}
 ### Commands
 ```bash
-{{#if TEST_COMMAND}}
-# Tests
-{{TEST_COMMAND}}
-{{/if}}
-
-{{#if BUILD_COMMAND}}
-# Build
-{{BUILD_COMMAND}}
-{{/if}}
-
-{{#if LINT_COMMAND}}
-# Linting
-{{LINT_COMMAND}}
-{{/if}}
+{{{ESSENTIAL_COMMANDS}}}
 ```
 
+{{/if}}
 ---
 
 {{#if LANGUAGE_DROIDS}}
@@ -395,22 +389,24 @@ Task(subagent_type: "documentation-expert", prompt: "Check: <files>")
 | Droid | Purpose |
 |-------|---------|
 {{{LANGUAGE_DROIDS}}}
-{{/if}}
 
-{{#if DISCOVERED_SKILLS}}
-### Skills
-| Skill | Purpose | When to Use |
-|-------|---------|-------------|
-{{{DISCOVERED_SKILLS}}}
 {{/if}}
+{{#if DISCOVERED_SKILLS}}
+### Commands
+| Command | Purpose |
+|---------|---------|
+| `/worktree` | Manage worktrees (create, list, pr, cleanup) |
+| `/code-review` | Full parallel review pipeline |
+| `/pr-ready` | Validate branch, create PR |
 
+{{/if}}
 {{#if MCP_PLUGINS}}
 ### MCP Plugins
 | Plugin | Purpose |
 |--------|---------|
 {{{MCP_PLUGINS}}}
-{{/if}}
 
+{{/if}}
 ---
 
 {{#if HAS_INFRA}}
@@ -418,52 +414,47 @@ Task(subagent_type: "documentation-expert", prompt: "Check: <files>")
 
 {{{INFRA_WORKFLOW}}}
 
----
 {{/if}}
-
 ## 🧪 Testing Requirements
-
 1. Create worktree
-2. Apply CODE FIELD (state assumptions first)
-3. Update/create tests
-4. Run `{{TEST_COMMAND}}`
-{{#if LINT_COMMAND}}
-5. Run `{{LINT_COMMAND}}`
-{{/if}}
-6. Create PR (do not merge with failing tests)
+2. Update/create tests
+3. Run `{{TEST_COMMAND}}`
+4. Run linting
+5. Create PR
 
 ---
 
 {{#if TROUBLESHOOTING}}
 ## 🔧 Troubleshooting
-
 {{{TROUBLESHOOTING}}}
 
----
 {{/if}}
-
-{{#if KEY_CONFIG_FILES}}
 ## ⚙️ Config Files
-
 | File | Purpose |
 |------|---------|
+{{#if KEY_CONFIG_FILES}}
 {{{KEY_CONFIG_FILES}}}
+{{else}}
+| `README.md` | Project documentation |
+| `.uam.json` | UAM agent memory configuration |
+| `package.json` | Node.js project configuration |
+| `tsconfig.json` | TypeScript configuration |
+| `.gitignore` | Git ignore patterns |
+{{/if}}
 
 ---
-{{/if}}
 
 ## ✅ Completion Checklist
 
 ```
-☐ Memory queried before starting
-☐ CODE FIELD applied (assumptions stated)
 ☐ Tests pass
 ☐ Lint/typecheck pass  
 ☐ Worktree used (not {{DEFAULT_BRANCH}})
-☐ Learnings stored in memory
-☐ PR created with parallel reviews
+☐ Memory updated
+☐ PR created
+☐ Parallel reviews passed
 {{#if HAS_INFRA}}
-☐ Infrastructure plan verified
+☐ Terraform plan verified
 {{/if}}
 ☐ No secrets in code
 ```
@@ -498,24 +489,23 @@ Task(subagent_type: "documentation-expert", prompt: "Check: <files>")
 │                                                                  │
 │  4. FIX (if issues found)                                        │
 │     ├─ Create new worktree for fix                              │
-│     ├─ Apply CODE FIELD for fix                                 │
+│     ├─ Fix the issue                                            │
 │     ├─ GOTO step 1 (Merge)                                      │
 │     └─ Repeat until 100% working                                │
 │                                                                  │
 │  5. COMPLETE                                                     │
-│     ├─ Do not skip: uam memory store "what I learned"           │
+│     ├─ Update memory with learnings                             │
 │     ├─ Close related tasks/issues                               │
 │     └─ Announce completion                                      │
 │                                                                  │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
-**⚠️ Do not say "done" or "complete" until:**
+**⚠️ NEVER say "done" or "complete" until:**
 - PR is merged (not just created)
 - Deployment succeeded (not just triggered)
 - Functionality verified working (not just "should work")
 - All errors/issues fixed (iterate as needed)
-- Learnings stored in memory
 
 **Commands for completion:**
 ```bash
@@ -530,7 +520,7 @@ gh run view <run-id>
 
 # If issues found, fix immediately
 {{WORKTREE_CREATE_CMD}} hotfix-<issue>
-# ... apply CODE FIELD, fix, test, PR, merge, repeat
+# ... fix, test, PR, merge, repeat
 ```
 
 ---
@@ -541,22 +531,31 @@ gh run view <run-id>
 {{#if RECENT_ACTIVITY}}
 ### Recent Activity
 {{{RECENT_ACTIVITY}}}
-{{/if}}
 
+{{/if}}
 {{#if LEARNED_LESSONS}}
 ### Lessons
 {{{LEARNED_LESSONS}}}
-{{/if}}
 
+{{/if}}
 {{#if KNOWN_GOTCHAS}}
 ### Gotchas
 {{{KNOWN_GOTCHAS}}}
-{{/if}}
 
+{{/if}}
 {{#if HOT_SPOTS}}
 ### Hot Spots
 {{{HOT_SPOTS}}}
+
 {{/if}}
 {{/if}}
-
 </coding_guidelines>
+
+---
+
+## Repository Structure
+
+```
+{{PROJECT_NAME}}/
+{{{REPOSITORY_STRUCTURE}}}
+```