Universal Agent Memory (UAM)

AI coding assistants that remember

Every lesson learned. Every bug fixed. Every architectural decision.

Not just in one conversation—but forever.

Quick Start (30 seconds)

# Install
npm install -g universal-agent-memory

# Run complete setup (installs dependencies, git hooks, etc.)
npm run setup

# Initialize in your project
uam init

That's it. Your AI now has persistent memory and follows proven workflows.

Complete Setup

For a full installation with all features:

# Install UAM CLI
npm install -g universal-agent-memory

# Run comprehensive setup
npm run setup
# This will:
# ✓ Check and install dependencies
# ✓ Install npm packages
# ✓ Build TypeScript
# ✓ Configure git hooks (pre-commit, commit-msg, pre-push)
# ✓ Set up GitHub PR templates

Requirements

Required:

• Node.js >= 18.0.0
• npm
• git
• npx

Optional (recommended):

• Docker - for local Qdrant semantic search
• Python 3 - for Pattern RAG indexing
• pre-commit - for advanced git hooks

Installing Dependencies

macOS:

brew install node git python docker

Ubuntu/Debian:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs python3 docker.io

Windows:

winget install OpenJS.NodeJS.LTS
winget install Git.Git
winget install Python.Python.3.12
winget install Docker.DockerDesktop

Recommended Platform: opencode

UAM is optimized for opencode - the local AI coding platform that provides:

• Persistent sessions - Memory survives across sessions
• Plugin architecture - Pattern RAG, session hooks, and more
• Local LLM support - Run Qwen3.5 35B locally via llama.cpp
• Built-in tooling - File operations, bash, search, todo management

Setup opencode (Recommended)

# Install opencode
npm install -g opencode

# Configure local LLM (optional, requires llama.cpp server)
# See: https://opencode.ai/docs/configuration

# Initialize UAM in your project
cd your-project
uam init

The opencode.json configuration file automatically loads UAM plugins for:

• Pattern RAG - Context-aware pattern injection (~12K tokens saved)
• Session hooks - Pre-execution setup, memory preservation
• Agent coordination - Multi-agent workflows without conflicts

Other Supported Platforms

| Platform | Notes | | --------------- | --------------------------------------- | | Factory.AI | Works well, use CLAUDE.md for context | | Claude Code | Desktop app, full UAM support | | VSCode | Use with Claude Code extension | | claude.ai | Web version, limited tooling |

What UAM Gives You

🧠 Persistent Memory

Your AI never forgets:

# Store a lesson
uam memory store "Always validate CSRF tokens in auth flows"

# Query later (any agent, any session)
uam memory query "auth security"

Memory persists in SQLite databases that travel with your code:

• agents/data/memory/short_term.db - Recent actions + session memories
• Semantic search via Qdrant (optional, uam memory start)

🎯 Pattern Router

Before every task, UAM auto-selects relevant patterns:

=== PATTERN ROUTER ===
Task: Fix authentication bug
Classification: bug-fix
ACTIVE: P3, P12, P17
BLOCKING: [none]
=== END ===

58 battle-tested patterns from Terminal-Bench 2.0 analysis:

• P12 - Verify outputs exist (fixes 37% of failures)
• P17 - Extract hidden constraints ("exactly", "only", "single")
• P3 - Backup before destructive actions
• P20 - Attack mindset for security tasks

🛡️ Completion Gates

Three mandatory checks before "done":

1. Output Existence - All expected files exist
2. Constraint Compliance - All requirements verified
3. Tests Pass - npm test 100%

🌳 Safe Worktrees

No more accidental commits to main:

uam worktree create my-feature
# → Creates isolated branch in .worktrees/
# → All changes tracked
uam worktree pr <id>
# → Creates PR, triggers reviews
uam worktree cleanup <id>
# → Clean removal after merge

🤖 Expert Droids

Tasks automatically route to specialists:

| Task Type | Routed To | | --------------- | ------------------------ | | TypeScript/JS | typescript-node-expert | | Security review | security-auditor | | Performance | performance-optimizer | | Documentation | documentation-expert |

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
3. AI reads CLAUDE.md - Follows embedded workflows automatically
4. Every task:
   • Pattern Router classifies task and selects patterns
   • Adaptive context loads relevant memory
   • Agent coordination checks for conflicts
   • Worktree created for isolated changes
   • Completion gates verify outputs, constraints, tests
   • Learnings stored in memory

Commands

Essential

| Command | Description | | -------------- | ------------------------------------------------ | | uam init | Initialize/update UAM (never loses data) | | uam generate | Regenerate CLAUDE.md from project analysis | | uam update | Update templates while preserving customizations |

Memory

| Command | Description | | ---------------------------- | -------------------------------- | | uam memory status | Check memory system status | | uam memory query <search> | Search memories | | uam memory store <content> | Store a learning | | uam memory start | Start Qdrant for semantic search |

Tasks

| Command | Description | | ----------------------- | -------------------------------------- | | uam task create | Create tracked task | | uam task list | List all tasks | | uam task claim <id> | Claim task (announces to other agents) | | uam task release <id> | Complete task |

Worktrees

| Command | Description | | ---------------------------- | ----------------------- | | uam worktree create <name> | Create isolated branch | | uam worktree pr <id> | Create PR from worktree | | uam worktree cleanup <id> | Remove worktree |

Droids

| Command | Description | | ----------------------- | ---------------------------- | | uam droids list | List available expert droids | | uam droids add <name> | Create new expert droid |

Architecture

4-Layer Memory System

┌─────────────────────────────────────────────────────────────────┐
│  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     │
└─────────────────────────────────────────────────────────────────┘

Hierarchical Memory (Hot/Warm/Cold)

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

Pattern RAG

Dynamically retrieves relevant patterns from Qdrant:

• Queries agent_patterns collection
• Injects ~2 patterns per task (saves ~12K tokens)
• Filters by similarity score (default 0.35)
• Avoids duplicate injections per session

Configuration

opencode.json (Platform-specific)

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "llama.cpp": {
      "name": "llama-server (local)",
      "options": {
        "baseURL": "http://localhost:8080/v1",
        "apiKey": "sk-qwen35b"
      },
      "models": {
        "qwen35-a3b-iq4xs": {
          "name": "Qwen3.5 35B A3B (IQ4_XS)",
          "limit": {
            "context": 262144,
            "output": 16384
          }
        }
      }
    }
  },
  "model": "llama.cpp/qwen35-a3b-iq4xs"
}

.uam.json (Project-specific)

{
  "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"
  }
}

Requirements

Required Dependencies

| Dependency | Version | Purpose | | ---------- | ----------------- | --------------------------- | | Node.js | >= 18.0.0 | Runtime environment | | npm | Latest | Package manager | | git | Latest | Version control (git hooks) | | npx | Included with npm | Run CLI tools |

Optional Dependencies

| Dependency | Purpose | Installation | | ---------- | -------------------------------- | ---------------------------------------------- | | Docker | Local Qdrant for semantic search | get.docker.com | | Python 3 | Pattern RAG indexing | brew install python or apt install python3 | | pre-commit | Advanced git hooks | pip install pre-commit |

Platform-Specific Setup

macOS:

brew install node@18 git python docker

Ubuntu/Debian:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs python3 docker.io

Windows (PowerShell):

winget install OpenJS.NodeJS.LTS
winget install Git.Git
winget install Python.Python.3.12
winget install Docker.DockerDesktop

Testing & Quality

# Run tests
npm test

# Run linter
npm run lint

# Build TypeScript
npm run build

Documentation

Core CLAUDE.md Sections

| File | Purpose | | ------------------------ | -------------------------------- | | CLAUDE_ARCHITECTURE.md | Cluster topology, IaC rules | | CLAUDE_CODING.md | Coding standards, security | | CLAUDE_WORKFLOWS.md | Task workflows, completion gates | | CLAUDE_MEMORY.md | Memory system, Pattern RAG | | CLAUDE_DROIDS.md | Available droids/skills |

Deep Dive

| Document | Description | | ---------------------------------------------------------------------- | -------------------------- | | docs/UAM_COMPLETE_ANALYSIS.md | Full system architecture | | docs/TERMINAL_BENCH_LEARNINGS.md | Universal agent patterns | | docs/BEHAVIORAL_PATTERNS.md | What works vs what doesn't | | benchmark-results/ | Terminal-Bench 2.0 results |

What's Next

UAM v5.0 includes:

• ✅ 58 Optimizations - Battle-tested from Terminal-Bench 2.0
• ✅ Pattern Router - Auto-selects optimal patterns per task
• ✅ 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
• ✅ Pattern RAG - Context-aware pattern injection (~12K tokens saved)
• ✅ opencode Integration - Plugin system for seamless integration
• ✅ Model Router - Per-model performance fingerprints

Attribution

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

Terminal-Bench patterns from Terminal-Bench 2.0 benchmarking.

Documentation · Issues · npm

Built for developers who want AI that learns.