universal-agent-memory

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":

• Output Existence - All expected files exist
• Constraint Compliance - All requirements verified
• 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

• Install & init - npm i -g universal-agent-memory && uam init
• CLAUDE.md generated - Auto-populated with project structure, commands, patterns
• AI reads CLAUDE.md - Follows embedded workflows automatically
• 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.