| Command | Description |
|---------|-------------|
| uam task create | Create tracked task |
| uam task list | List all tasks |
| uam task claim | Claim task (announces to other agents) |
| uam task release | Complete task |
| uam task ready | List tasks ready to work on |
| uam task stats | Show task statistics |

$3

| Command | Description |
|---------|-------------|
| uam worktree create | Create isolated branch |
| uam worktree pr | Create PR from worktree |
| uam worktree cleanup | Remove worktree |
| uam worktree list | List all worktrees |

$3

| Command | Description |
|---------|-------------|
| uam droids list | List available expert droids |
| uam droids add | Create new expert droid |
| uam droids import | Import droids from another platform |

$3

| Command | Description |
|---------|-------------|
| uam agent status | View active agents |
| uam agent overlaps | Check for file conflicts |
| uam agent announce | Announce intent to work on a resource |
| uam coord status | Coordination overview |

$3

| Command | Description |
|---------|-------------|
| uam deploy queue | Queue a deploy action for batching |
| uam deploy batch | Create a batch from pending actions |
| uam deploy execute | Execute a deploy batch |
| uam deploy flush | Flush all pending deploys |

$3

| Command | Description |
|---------|-------------|
| uam model status | Show model router status |
| uam model list | List available models |
| uam model fingerprint | Show model performance fingerprints |

$3

| Command | Description |
|---------|-------------|
| uam mcp-router start | Start hierarchical MCP router |
| uam mcp-router stats | Show router statistics and token savings |
| uam mcp-router discover | Discover tools matching a query |
| uam mcp-router list | List configured MCP servers |

How It Works

1. Install & Init: npm i -g universal-agent-memory && uam init

2. CLAUDE.md Generated: Auto-populated with project structure, commands, patterns, droids, and memory system instructions

3. AI Reads CLAUDE.md: Follows the embedded workflows automatically

4. Every Task:
- Pattern Router classifies task and selects applicable patterns
- Adaptive context decides what memory to load (none/minimal/full)
- Dynamic retrieval queries relevant memories from all tiers
- Check for agent overlaps before starting work
- Route to specialist droids if needed
- Create worktree for isolated changes
- Apply Code Field for better code generation
- Run completion gates: outputs exist, constraints met, tests pass
- Store learnings in memory for future sessions

5. Close-Out: Merge → Deploy → Monitor → Fix loop until 100%

Memory Architecture

$3

`
┌─────────────────────────────────────────────────────────────────┐
│ L1: WORKING │ Recent actions │ 50 max │ SQLite │
│ L2: SESSION │ Current session │ Per run │ SQLite │
│ L3: SEMANTIC │ Long-term learnings │ Qdrant │ Vectors │
│ L4: KNOWLEDGE │ Entity relationships │ SQLite │ Graph │
└─────────────────────────────────────────────────────────────────┘
`

$3

On top of the 4-layer system, UAM implements hierarchical memory management:

`
HOT (10 entries) → In-context, always included → <1ms access
WARM (50 entries) → Cached, promoted on access → <5ms access
COLD (500 entries) → Archived, semantic search only → ~50ms access
`

- Time-decay importance: importance * (0.95 ^ days_since_access)
- Auto-promotion: Frequently accessed cold/warm entries promote to hotter tiers
- Consolidation: Old warm entries summarized into compressed cold entries
- SQLite persistence: Survives across sessions via hierarchical_memory table

$3

The memory system selectively loads context based on task classification:

- 21 optimizations including SQLite-backed historical benefit tracking
- TF-IDF-like keyword scoring for section relevance
- 13 domain-specific context sections (security, file formats, git recovery, etc.)
- Error-to-section mapping for progressive escalation on failure
- Semantic caching for task-to-outcome mappings

$3

- Dynamic retrieval: Adaptive depth based on query complexity (simple/moderate/complex)
- Semantic compression: 2-3x token reduction while preserving meaning
- Speculative cache: Pre-warms queries based on category patterns
- Deduplication: SHA-256 content hash + Jaccard similarity (0.8 threshold)
- Feedback loop: recordTaskFeedback() captures success/failure to improve future runs
- Model router: Per-model performance fingerprints by task category

Data is never deleted. Memory databases persist with the project.

Update with uam init or uam generate always merges - nothing is lost.

Configuration

Configuration in .uam.json:

`json
{
"project": {
"name": "my-project",
"defaultBranch": "main"
},
"memory": {
"shortTerm": { "enabled": true, "path": "./agents/data/memory/short_term.db" },
"longTerm": { "enabled": true, "provider": "qdrant" }
},
"worktrees": {
"enabled": true,
"directory": ".worktrees"
},
"template": {
"sections": {
"codeField": true
}
}
}
`

Platform Support

| Platform | Context File | Works With |
|----------|--------------|------------|
| Claude Code | CLAUDE.md | Desktop app |
| Factory.AI | CLAUDE.md | Desktop/web |
| claude.ai | CLAUDE.md | Web browser |
| VSCode | CLAUDE.md | Extensions |

Built-in Expert Droids

| Droid | Specialization | When Used |
|-------|----------------|-----------|
| code-quality-guardian | SOLID, complexity, naming | Before every PR |
| security-auditor | OWASP, secrets, injection (enhanced with 150+ security sources) | Before every PR |
| performance-optimizer | Algorithms, memory, caching | On request |
| documentation-expert | JSDoc, README, accuracy | On request |
| debug-expert | Dependency conflicts, runtime errors, SWE-bench debugging | Error handling |
| sysadmin-expert | Kernel, QEMU, networking, DNS, systemd | Infrastructure tasks |
| ml-training-expert | Model training, MTEB, RL, datasets | ML tasks |
| terminal-bench-optimizer | Task routing, time budgets, strategy orchestration | Benchmarking |

Built-in Skills

| Skill | Purpose | Trigger |
|-------|---------|---------|
| balls-mode | Decomposed reasoning with confidence scoring | Complex decisions, debugging |
| cli-design-expert | CLI/TUI design patterns, UX, help systems | Building CLI tools |
| typescript-node-expert | TypeScript best practices, strict typing | TypeScript projects |
| terminal-bench-strategies | Proven strategies for Terminal-Bench tasks | Benchmark tasks |
| unreal-engine-developer | UE5, Blueprints, C++, Python scripting | Game development |
| sec-context-review | Security context review patterns | Security analysis |

Requirements

- Node.js 18+
- Git
- Docker (optional, for semantic search)

FAQ

Q: Do I need to manage memory manually?
A: No. The AI queries and stores memory automatically per CLAUDE.md instructions.

Q: What if I don't have Docker?
A: UAM works without Docker. You lose semantic search but SQLite memory still works.

Q: Can multiple AI agents work on the same project?
A: Yes. UAM includes coordination protocols to prevent merge conflicts.

Q: How do I update without losing my customizations?
A: Run uam init or uam generate`. Updates always merge - nothing is lost.

Q: What's Code Field?
A: A prompt technique that makes AI state assumptions before coding. Based on context-field research.

---

Deep Dive Documentation

Want to understand how UAM works under the hood?

$3

| Document | Description |
|----------|-------------|
| UAM Complete Analysis | Full system architecture, all features |
| Adaptive UAM Design | Hybrid adaptive context selector design |
| Multi-Model Architecture | Model routing and fingerprints |
| MCP Router Setup | Hierarchical MCP router for token reduction |

$3

| Document | Description |
|----------|-------------|
| Terminal-Bench Learnings | Universal agent patterns discovered |
| Behavioral Patterns | What works vs what doesn't analysis |
| Failing Tasks Solution Plan | Detailed fix strategies for each failure mode |
| Benchmark Results | All Terminal-Bench 2.0 run results |
| Benchmark Evolution | How benchmark performance evolved |
| Domain Strategy Guides | Task-specific strategies |

$3

| Document | Description |
|----------|-------------|
| UAM Performance Analysis | Performance metrics and analysis |
| Optimization Options | Available optimization strategies |
| V110 Pattern Analysis | Pattern effectiveness analysis |

---

What's Next?

UAM v2.7.0 includes 58 optimizations. Recent additions:

- ✅ 58 Optimizations - Battle-tested from Terminal-Bench 2.0
- ✅ Pattern Router - Auto-selects optimal patterns per task with blocking gates
- ✅ Completion Gates - 3 mandatory checks before "done"
- ✅ 8 Expert Droids - Specialized agents for common tasks
- ✅ 6 Skills - Reusable capabilities (balls-mode, CLI design, etc.)
- ✅ Pre-execution Hooks - Task-specific setup before agent runs
- ✅ Hierarchical Memory - Hot/warm/cold tiering with auto-promotion
- ✅ Adaptive Context - Selective context loading based on task type
- ✅ MCP Router - 98%+ token reduction for multi-tool contexts
- ✅ Harbor Integration - Terminal-Bench 2.0 benchmarking agent
- ✅ Model Router - Per-model performance fingerprints

Coming soon:

- Cross-Project Learning - Share patterns between codebases
- Visual Memory Dashboard - See what your AI knows
- Continuous Benchmark Tracking - Auto-run benchmarks on template changes

Star the repo to follow updates. Open an issue to request features.

---

Attribution

Code Field prompts based on research from NeoVertex1/context-field.

License

MIT

---