universal-agent-memory 0.5.2 → 0.5.4

package/templates/CLAUDE.template.md

@@ -1,11 +1,24 @@
 <!--
-  CLAUDE.md Universal Template - v7.0
+  CLAUDE.md Universal Template - v9.0
   
   CHANGES IN THIS VERSION:
-  - All project-specific content uses Handlebars placeholders
-  - No hardcoded project data (Pay2U removed)
-  - Simplified memory references (agent-managed, not user-managed)
-  - Template variables documented inline
+  - 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:
+  https://github.com/NeoVertex1/context-field
+  
+  Context Field is experimental research on context field prompts and cognitive
+  regime shifts in large language models. The code_field.md prompt produces:
+  - 100% assumption stating (vs 0% baseline)
+  - 89% bug detection in code review (vs 39% baseline)
+  - 100% refusal of impossible requests (vs 0% baseline)
+  
+  License: Research shared for exploration and reuse with attribution.
   
   Core Variables:
     {{PROJECT_NAME}}, {{PROJECT_PATH}}, {{DEFAULT_BRANCH}}, {{STRUCTURE_DATE}}
@@ -24,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}}
 
 ---
@@ -50,13 +63,53 @@
 
 ---
 
+## 🧬 CODE FIELD - COGNITIVE ENVIRONMENT
+
+**Apply to ALL code generation. Creates conditions where better code emerges naturally.**
+
+### Core Inhibitions
+
+```
+Do not write code before stating assumptions.
+Do not claim correctness you haven't verified.
+Do not handle only the happy path.
+Under what conditions does this work?
+```
+
+### 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
+
+- 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
+
+### Expected Output Format
+
+**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)*
+
+---
+
 ## ⚡ SESSION START PROTOCOL
 
 **EXECUTE IMMEDIATELY before any response:**
 
 ```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
 ```
 
@@ -131,60 +184,81 @@ Task(subagent_type: "performance-optimizer", ...) # Runs concurrently
 │                    EXECUTE FOR EVERY TASK                        │
 ├─────────────────────────────────────────────────────────────────┤
 │                                                                  │
-│  1. MEMORY   │ 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   │ uam agent overlaps --resource "<files>"           │
+│  2. AGENTS   │ uam agent overlaps --resource "<files>"          │
 │              │ If overlap: coordinate or wait                    │
 │                                                                  │
 │  3. SKILLS   │ Check {{SKILLS_PATH}} for applicable skill        │
 │              │ Invoke BEFORE implementing                        │
 │                                                                  │
-│  4. WORKTREE │ {{WORKTREE_CREATE_CMD}} <slug>                    │
-│              │ cd {{WORKTREE_DIR}}/NNN-<slug>/                   │
-│              │ NEVER commit to {{DEFAULT_BRANCH}}                │
+│  4. WORKTREE │ {{WORKTREE_CREATE_CMD}} <slug>                   │
+│              │ cd {{WORKTREE_DIR}}/NNN-<slug>/                  │
+│              │ NEVER commit to {{DEFAULT_BRANCH}}               │
 │                                                                  │
-│  5. WORK     │ Implement → Test → {{WORKTREE_PR_CMD}}            │
+│  5. WORK     │ Implement → Test → {{WORKTREE_PR_CMD}}           │
 │                                                                  │
-│  6. MEMORY   │ Store important learnings for future sessions     │
-│              │ uam memory store "lesson" --importance 7+         │
+│  6. MEMORY   │ Update short-term after actions                   │
+│              │ Update session_memories for decisions             │
+│              │ Store lessons in long-term (importance 7+)        │
 │                                                                  │
-│  7. VERIFY   │ ☐ Memory ☐ Worktree ☐ PR ☐ Skills ☐ Agents        │
+│  7. VERIFY   │ ☐ Memory ☐ Worktree ☐ PR ☐ Skills ☐ Agents      │
 │                                                                  │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
 ---
 
-## 🧠 MEMORY SYSTEM
-
-**Memory is managed automatically.** Query for context, store important learnings.
+## 🧠 FOUR-LAYER MEMORY SYSTEM
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
-│  L1: WORKING      │ Recent actions       │ {{SHORT_TERM_LIMIT}} max │ Auto-managed  │
-│  L2: SESSION      │ Current session      │ Per session              │ Auto-managed  │
-│  L3: SEMANTIC     │ Long-term learnings  │ {{LONG_TERM_BACKEND}}    │ Store lessons │
-│  L4: KNOWLEDGE    │ Entity relationships │ SQLite                   │ Auto-managed  │
+│  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
+
+| 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 |
+
+### Memory Commands
+
+```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
 
-| 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` |
-| Completed a task | Memory auto-updates |
+- **Trigger**: Every 10 working memory entries
+- **Action**: Summarize → session_memories, Extract lessons → semantic memory
+- **Dedup**: Skip if content_hash exists OR similarity > 0.92
 
-### When to Query Memories
+### Decay Formula
 
-| Situation | Action |
-|-----------|--------|
-| Starting new work | `uam memory query "relevant keywords"` |
-| Debugging | `uam memory query "similar error"` |
-| Understanding patterns | `uam memory query "how we did X"` |
+```
+effective_importance = importance × (0.95 ^ days_since_access)
+```
 
 ---
 
@@ -265,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
 
@@ -299,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}}
@@ -333,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}}
@@ -356,38 +414,35 @@ Task(subagent_type: "documentation-expert", prompt: "Check: <files>")
 
 {{{INFRA_WORKFLOW}}}
 
----
 {{/if}}
-
 ## 🧪 Testing Requirements
-
 1. Create worktree
 2. Update/create tests
 3. Run `{{TEST_COMMAND}}`
-{{#if LINT_COMMAND}}
-4. Run `{{LINT_COMMAND}}`
-{{/if}}
+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
 
@@ -395,11 +450,11 @@ Task(subagent_type: "documentation-expert", prompt: "Check: <files>")
 ☐ Tests pass
 ☐ Lint/typecheck pass  
 ☐ Worktree used (not {{DEFAULT_BRANCH}})
-☐ Memory updated (if learned something)
+☐ Memory updated
 ☐ PR created
 ☐ Parallel reviews passed
 {{#if HAS_INFRA}}
-☐ Infrastructure plan verified
+☐ Terraform plan verified
 {{/if}}
 ☐ No secrets in code
 ```
@@ -439,7 +494,7 @@ Task(subagent_type: "documentation-expert", prompt: "Check: <files>")
 │     └─ Repeat until 100% working                                │
 │                                                                  │
 │  5. COMPLETE                                                     │
-│     ├─ Store learnings: uam memory store "what I learned"       │
+│     ├─ Update memory with learnings                             │
 │     ├─ Close related tasks/issues                               │
 │     └─ Announce completion                                      │
 │                                                                  │
@@ -476,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}}}
+```