universal-agent-memory 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +274 -189
  2. package/dist/analyzers/index.d.ts.map +1 -1
  3. package/dist/analyzers/index.js +203 -0
  4. package/dist/analyzers/index.js.map +1 -1
  5. package/dist/generators/claude-md.js +42 -0
  6. package/dist/generators/claude-md.js.map +1 -1
  7. package/package.json +1 -1
  8. package/templates/CLAUDE.template.md +222 -77
package/README.md CHANGED
@@ -1,215 +1,309 @@
1
- # Universal Agent Memory
1
+ # Universal Agent Memory (UAM)
2
2
 
3
- Universal AI agent memory system for Claude Code, Factory.AI, VSCode, OpenCode, and web-based LLMs.
3
+ [![npm version](https://img.shields.io/npm/v/universal-agent-memory.svg)](https://www.npmjs.com/package/universal-agent-memory)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
4
5
 
5
- Provides:
6
- - **CLAUDE.md template system** with automatic project analysis and generation
7
- - **Memory system** with flexible backends:
8
- - **Desktop**: SQLite short-term + local Qdrant or cloud backends
9
- - **Web**: IndexedDB short-term + GitHub/Qdrant Cloud long-term
10
- - **Git worktree workflow** automation for isolated development
11
- - **Cross-platform compatibility** for all major AI coding assistants (desktop and web)
6
+ A complete autonomous agent operating system for AI coding assistants. Provides memory, task management, agent coordination, and workflow automation for Claude Code, Factory.AI, VSCode, OpenCode, and web-based LLMs.
7
+
8
+ ## What It Does
9
+
10
+ UAM transforms AI coding assistants into autonomous agents with:
11
+
12
+ - **4-Layer Memory System** - Working, session, semantic, and knowledge graph memory
13
+ - **Task Management** - Git-backed issue tracking with dependency DAG (superior to Beads)
14
+ - **Agent Coordination** - Multi-agent overlap detection and merge conflict prevention
15
+ - **Deploy Batching** - Batch commits/pushes to save CI minutes
16
+ - **Git Worktree Automation** - Isolated development branches with PR workflows
17
+ - **CLAUDE.md Generation** - Auto-generated project context files
12
18
 
13
19
  ## Installation
14
20
 
15
- ### Desktop (CLI)
21
+ ### Quick Install (Recommended)
16
22
 
17
23
  ```bash
18
- # Automatic installer with Docker detection
19
- bash <(curl -fsSL https://raw.githubusercontent.com/DammianMiller/universal-agent-memory/main/scripts/install-desktop.sh)
20
-
21
- # Or manually with npm
24
+ # Install globally
22
25
  npm install -g universal-agent-memory
23
26
 
24
- # Or use npx
25
- npx universal-agent-memory init --desktop
27
+ # Initialize in your project
28
+ cd your-project
29
+ uam init --interactive
26
30
  ```
27
31
 
28
- ### Web Browsers (claude.ai, factory.ai)
32
+ ### One-Line Installers
29
33
 
30
34
  ```bash
31
- # Quick web setup
32
- bash <(curl -fsSL https://raw.githubusercontent.com/DammianMiller/universal-agent-memory/main/scripts/install-web.sh)
35
+ # Desktop (with Docker for Qdrant)
36
+ bash <(curl -fsSL https://raw.githubusercontent.com/DammianMiller/universal-agent-memory/main/scripts/install-desktop.sh)
33
37
 
34
- # Or manually
35
- npx universal-agent-memory init --web
38
+ # Web browsers (claude.ai, factory.ai)
39
+ bash <(curl -fsSL https://raw.githubusercontent.com/DammianMiller/universal-agent-memory/main/scripts/install-web.sh)
36
40
  ```
37
41
 
38
- Web installations use:
39
- - **IndexedDB** for short-term memory (replaces SQLite)
40
- - **GitHub** or **Qdrant Cloud** for long-term memory (opt-in via env vars)
42
+ ### Using npx (No Install)
43
+
44
+ ```bash
45
+ npx universal-agent-memory init --interactive
46
+ ```
41
47
 
42
48
  ## Quick Start
43
49
 
44
50
  ```bash
45
- # Desktop initialization (default)
46
- uam init --desktop
51
+ # 1. Initialize project
52
+ uam init --with-memory --with-worktrees
53
+
54
+ # 2. Start memory services (requires Docker)
55
+ uam memory start
47
56
 
48
- # Web initialization (for claude.ai, factory.ai)
49
- uam init --web
57
+ # 3. Generate CLAUDE.md
58
+ uam generate
50
59
 
51
- # Interactive mode (asks questions)
52
- uam init --interactive
60
+ # 4. Create your first task
61
+ uam task create --title "My first task" --type task
53
62
 
54
- # Or with specific options
55
- uam init --platform factory --with-memory --with-worktrees
63
+ # 5. Start working
64
+ uam task claim <task-id>
65
+ uam worktree create my-feature
56
66
  ```
57
67
 
58
- This will:
59
- 1. Analyze your project structure
60
- 2. Generate a customized `CLAUDE.md`
61
- 3. Set up platform-specific directories (`.factory/`, `.claude/`, etc.)
62
- 4. Optionally configure memory system and worktree workflow
68
+ ## Core Features
63
69
 
64
- ## Commands
70
+ ### Task Management
65
71
 
66
- ### Initialize Project
72
+ A complete task tracking system integrated with memory and coordination.
67
73
 
68
74
  ```bash
69
- uam init [options]
70
-
71
- Options:
72
- -p, --platform <platforms...> Target platforms (claude, factory, vscode, opencode, claudeWeb, factoryWeb, all)
73
- --desktop Desktop mode (SQLite + local Qdrant)
74
- --web Web mode (IndexedDB + cloud backends)
75
- --interactive Interactive setup with prompts
76
- --with-memory Set up memory system
77
- --with-worktrees Set up git worktree workflow
78
- --force Overwrite existing configuration
75
+ # Create tasks
76
+ uam task create --title "Fix auth bug" --type bug --priority 0
77
+ uam task create --title "Add dark mode" --type feature --priority 2
78
+
79
+ # View tasks
80
+ uam task list # All open tasks
81
+ uam task ready # Tasks with no blockers
82
+ uam task blocked # Blocked tasks
83
+ uam task stats # Statistics
84
+
85
+ # Work on tasks
86
+ uam task claim <id> # Claim task (announces to other agents)
87
+ uam task show <id> # View details
88
+ uam task release <id> --reason "Fixed" # Complete task
89
+
90
+ # Dependencies
91
+ uam task dep --from <child> --to <parent> # Add blocker
92
+ uam task undep --from <child> --to <parent># Remove blocker
93
+
94
+ # Git sync (version control your tasks)
95
+ uam task sync # Export to JSONL
96
+ uam task compact --days 90 # Archive old tasks
79
97
  ```
80
98
 
81
- ### Analyze Project
99
+ **Task Types**: `task`, `bug`, `feature`, `chore`, `epic`, `story`
82
100
 
83
- ```bash
84
- uam analyze [options]
101
+ **Priority Levels**: P0 (critical) → P4 (backlog)
85
102
 
86
- Options:
87
- -o, --output <format> Output format (json, yaml, md)
88
- --save Save analysis to file
89
- ```
103
+ ### Memory System
90
104
 
91
- ### Generate Files
105
+ 4-layer architecture for complete context retention.
92
106
 
93
107
  ```bash
94
- uam generate [options]
108
+ # Start services
109
+ uam memory start # Start Qdrant (Docker)
110
+ uam memory status # Check status
111
+ uam memory stop # Stop services
112
+
113
+ # Query memories
114
+ uam memory query "authentication JWT" # Semantic search
95
115
 
96
- Options:
97
- -f, --force Overwrite without confirmation
98
- -d, --dry-run Preview without writing
99
- -p, --platform Generate for specific platform only
116
+ # Store learnings
117
+ uam memory store "lesson learned" --tags "auth,security" --importance 8
100
118
  ```
101
119
 
102
- **Smart Merging**: When a `CLAUDE.md` or `AGENT.md` file already exists, the CLI will offer to:
103
- - **Merge** (recommended): Updates standard sections while preserving your custom sections
104
- - **Overwrite**: Replace the entire file with newly generated content
105
- - **Cancel/Skip**: Leave the existing file unchanged
120
+ **Layers:**
106
121
 
107
- The merge strategy:
108
- - Updates the preamble (project name, description) from new analysis
109
- - Replaces standard sections (Memory System, Browser Usage, Quick Reference, etc.) with updated versions
110
- - Preserves any custom sections you've added
111
- - Appends custom sections at the end of the file
122
+ | Layer | Storage | Purpose | Speed |
123
+ |-------|---------|---------|-------|
124
+ | L1: Working | SQLite | Recent actions (last 50) | ~0.15ms |
125
+ | L2: Session | SQLite | Session decisions | ~0.2ms |
126
+ | L3: Semantic | Qdrant | Reusable learnings | ~1-2ms |
127
+ | L4: Knowledge Graph | SQLite | Entity relationships | ~0.17ms |
112
128
 
113
- ### Memory Management
129
+ ### Agent Coordination
130
+
131
+ Multi-agent support with overlap detection and messaging.
114
132
 
115
133
  ```bash
116
- # Check status
117
- uam memory status
134
+ # Register agent
135
+ uam agent register --name "feature-agent" --capabilities "coding,review"
118
136
 
119
- # Start memory services (Qdrant)
120
- uam memory start
137
+ # Announce work (enables overlap detection)
138
+ uam agent announce --id <agent-id> --resource "src/auth/" --intent editing
121
139
 
122
- # Stop services
123
- uam memory stop
140
+ # Check for conflicts
141
+ uam agent overlaps --resource "src/auth/"
124
142
 
125
- # Query long-term memory
126
- uam memory query "search term" --limit 10
143
+ # Complete work
144
+ uam agent complete --id <agent-id> --resource "src/auth/"
127
145
 
128
- # Store a memory
129
- uam memory store "lesson learned" --tags "tag1,tag2" --importance 8
146
+ # Status
147
+ uam agent status # View all agents
148
+ uam coord status # Coordination overview
130
149
  ```
131
150
 
132
- ### Git Worktrees
151
+ **Conflict Risk Levels**: `none`, `low`, `medium`, `high`, `critical`
133
152
 
134
- ```bash
135
- # Create new worktree
136
- uam worktree create my-feature
153
+ ### Deploy Batching
137
154
 
138
- # List worktrees
139
- uam worktree list
155
+ Batch multiple commits/pushes to reduce CI runs.
156
+
157
+ ```bash
158
+ # Queue commits
159
+ uam deploy queue --agent-id <id> --action-type commit \
160
+ --message "feat: add feature" --files "src/feature.ts"
140
161
 
141
- # Create PR from worktree
142
- uam worktree pr 001
162
+ # View queue
163
+ uam deploy status
143
164
 
144
- # Cleanup after merge
145
- uam worktree cleanup 001
165
+ # Execute batched deploys
166
+ uam deploy flush # Squashes commits, single push
146
167
  ```
147
168
 
148
- ### Droids/Agents
169
+ ### Git Worktrees
170
+
171
+ Isolated development branches with automated PR workflow.
149
172
 
150
173
  ```bash
151
- # List available droids
152
- uam droids list
174
+ # Create worktree
175
+ uam worktree create my-feature # Creates feature/NNN-my-feature
176
+
177
+ # List worktrees
178
+ uam worktree list
153
179
 
154
- # Add a new droid
155
- uam droids add my-droid --template code-reviewer
180
+ # Create PR
181
+ uam worktree pr <id> # Push + create PR
156
182
 
157
- # Import from another platform
158
- uam droids import ~/.claude/agents/
183
+ # Cleanup
184
+ uam worktree cleanup <id> # Remove worktree + delete branch
159
185
  ```
160
186
 
161
- ### Platform Sync
187
+ ### CLAUDE.md Generation
188
+
189
+ Auto-generate context files for AI assistants.
162
190
 
163
191
  ```bash
164
- # Sync between platforms
165
- uam sync --from claude --to factory
192
+ # Analyze project
193
+ uam analyze --output json
194
+
195
+ # Generate CLAUDE.md
196
+ uam generate # Interactive merge with existing
197
+ uam generate --force # Overwrite
198
+ uam generate --dry-run # Preview only
166
199
  ```
167
200
 
201
+ ## Command Reference
202
+
203
+ ### Core Commands
204
+
205
+ | Command | Description |
206
+ |---------|-------------|
207
+ | `uam init` | Initialize UAM in a project |
208
+ | `uam analyze` | Analyze project structure |
209
+ | `uam generate` | Generate CLAUDE.md |
210
+ | `uam sync` | Sync between platforms |
211
+
212
+ ### Task Commands
213
+
214
+ | Command | Description |
215
+ |---------|-------------|
216
+ | `uam task create` | Create a new task |
217
+ | `uam task list` | List tasks (with filters) |
218
+ | `uam task show <id>` | Show task details |
219
+ | `uam task claim <id>` | Claim task for work |
220
+ | `uam task release <id>` | Complete and release task |
221
+ | `uam task ready` | Show unblocked tasks |
222
+ | `uam task blocked` | Show blocked tasks |
223
+ | `uam task dep` | Add dependency |
224
+ | `uam task stats` | Show statistics |
225
+ | `uam task sync` | Sync with JSONL |
226
+
227
+ ### Memory Commands
228
+
229
+ | Command | Description |
230
+ |---------|-------------|
231
+ | `uam memory start` | Start Qdrant (Docker) |
232
+ | `uam memory stop` | Stop memory services |
233
+ | `uam memory status` | Check service status |
234
+ | `uam memory query` | Semantic search |
235
+ | `uam memory store` | Store a learning |
236
+
237
+ ### Agent Commands
238
+
239
+ | Command | Description |
240
+ |---------|-------------|
241
+ | `uam agent register` | Register new agent |
242
+ | `uam agent announce` | Announce work on resource |
243
+ | `uam agent overlaps` | Check for conflicts |
244
+ | `uam agent complete` | Mark work complete |
245
+ | `uam agent status` | Show agent status |
246
+ | `uam agent broadcast` | Send to all agents |
247
+ | `uam agent send` | Direct message |
248
+ | `uam agent receive` | Get pending messages |
249
+
250
+ ### Coordination Commands
251
+
252
+ | Command | Description |
253
+ |---------|-------------|
254
+ | `uam coord status` | Overview of coordination |
255
+ | `uam coord flush` | Execute pending deploys |
256
+ | `uam coord cleanup` | Clean stale data |
257
+
258
+ ### Deploy Commands
259
+
260
+ | Command | Description |
261
+ |---------|-------------|
262
+ | `uam deploy queue` | Queue a deploy action |
263
+ | `uam deploy status` | View deploy queue |
264
+ | `uam deploy batch` | Create batch from queue |
265
+ | `uam deploy execute` | Execute a batch |
266
+ | `uam deploy flush` | Batch and execute all |
267
+
268
+ ### Worktree Commands
269
+
270
+ | Command | Description |
271
+ |---------|-------------|
272
+ | `uam worktree create` | Create feature worktree |
273
+ | `uam worktree list` | List all worktrees |
274
+ | `uam worktree pr` | Create PR from worktree |
275
+ | `uam worktree cleanup` | Remove worktree |
276
+
277
+ ### Droids Commands
278
+
279
+ | Command | Description |
280
+ |---------|-------------|
281
+ | `uam droids list` | List available droids |
282
+ | `uam droids add` | Add a new droid |
283
+ | `uam droids import` | Import from path |
284
+
168
285
  ## Configuration
169
286
 
170
287
  Configuration is stored in `.uam.json`:
171
288
 
172
289
  ```json
173
290
  {
174
- "$schema": "https://raw.githubusercontent.com/DammianMiller/universal-agent-memory/main/schema.json",
175
291
  "version": "1.0.0",
176
292
  "project": {
177
293
  "name": "my-project",
178
- "description": "Project description",
179
294
  "defaultBranch": "main"
180
295
  },
181
- "platform": "claudeCode",
182
- "platforms": {
183
- "claudeCode": { "enabled": true },
184
- "claudeWeb": { "enabled": false },
185
- "factory": { "enabled": true },
186
- "factoryWeb": { "enabled": false },
187
- "vscode": { "enabled": false },
188
- "opencode": { "enabled": false }
189
- },
190
296
  "memory": {
191
297
  "shortTerm": {
192
298
  "enabled": true,
193
299
  "path": "./agents/data/memory/short_term.db",
194
- "maxEntries": 50,
195
- "webDatabase": "agentContext",
196
- "forceDesktop": false
300
+ "maxEntries": 50
197
301
  },
198
302
  "longTerm": {
199
303
  "enabled": true,
200
304
  "provider": "qdrant",
201
305
  "endpoint": "localhost:6333",
202
- "collection": "agent_memory",
203
- "github": {
204
- "enabled": false,
205
- "repo": "owner/repo",
206
- "path": ".uam/memory"
207
- },
208
- "qdrantCloud": {
209
- "enabled": false,
210
- "url": "https://xxxxx.aws.cloud.qdrant.io:6333",
211
- "collection": "agent_memory"
212
- }
306
+ "collection": "agent_memory"
213
307
  }
214
308
  },
215
309
  "worktrees": {
@@ -222,100 +316,91 @@ Configuration is stored in `.uam.json`:
222
316
 
223
317
  ## Platform Support
224
318
 
225
- | Platform | Environment | Context File | Agents | Commands |
226
- |----------|-------------|--------------|--------|----------|
227
- | Claude Code | Desktop | `CLAUDE.md` | `.claude/agents/` | `.claude/commands/` |
228
- | claude.ai | Web | `CLAUDE.md` | Project context | N/A |
229
- | Factory.AI | Desktop | `CLAUDE.md` | `.factory/droids/` | `.factory/commands/` |
230
- | factory.ai | Web | `CLAUDE.md` | Project context | N/A |
231
- | VSCode | Desktop | `CLAUDE.md` | Extension-based | Tasks |
232
- | OpenCode | Desktop | `opencode.json` | `.opencode/agent/` | `.opencode/command/` |
233
-
234
- ## Built-in Droid Templates
235
-
236
- - `code-reviewer` - Reviews diffs for correctness and risks
237
- - `security-reviewer` - Finds security issues in code
238
- - `performance-reviewer` - Identifies performance bottlenecks
239
- - `test-writer` - Generates unit tests
240
-
241
- ## Memory System
242
-
243
- ### Desktop Environments
319
+ | Platform | Environment | Context File | Agents/Droids |
320
+ |----------|-------------|--------------|---------------|
321
+ | Claude Code | Desktop | `CLAUDE.md` | `.claude/agents/` |
322
+ | claude.ai | Web | `CLAUDE.md` | Project context |
323
+ | Factory.AI | Desktop | `CLAUDE.md` | `.factory/droids/` |
324
+ | factory.ai | Web | `CLAUDE.md` | Project context |
325
+ | VSCode | Desktop | `CLAUDE.md` | Extension-based |
326
+ | OpenCode | Desktop | `opencode.json` | `.opencode/agent/` |
244
327
 
245
- #### Short-term Memory (SQLite)
328
+ ## Workflow Engine
246
329
 
247
- Stores the last 50 actions/observations for immediate context. Automatically pruned.
330
+ UAM enforces a 5-phase workflow for every agent action:
248
331
 
249
- Location: `./agents/data/memory/short_term.db`
250
-
251
- #### Long-term Memory
252
-
253
- **Local Qdrant** (requires Docker):
254
- ```bash
255
- uam memory start
256
- ```
257
-
258
- **GitHub Backend** (opt-in):
259
- ```bash
260
- export GITHUB_TOKEN=your_token
261
- # Stores memories as JSON files in git repository
262
332
  ```
263
-
264
- **Qdrant Cloud** (opt-in, 1GB free tier):
265
- ```bash
266
- export QDRANT_API_KEY=your_key
267
- export QDRANT_URL=https://xxxxx.aws.cloud.qdrant.io:6333
333
+ START → TASK → CONTEXT → WORK → COMPLETE
268
334
  ```
269
335
 
270
- ### Web Environments (claude.ai, factory.ai)
336
+ 1. **START**: Check existing tasks, read memory
337
+ 2. **TASK**: Create/claim task before any work
338
+ 3. **CONTEXT**: Query memory, check skills
339
+ 4. **WORK**: Create worktree, make changes, test, PR
340
+ 5. **COMPLETE**: Update memory, release task
271
341
 
272
- #### Short-term Memory (IndexedDB)
342
+ Each phase has **gates** that must pass before proceeding.
273
343
 
274
- Browser-native storage for recent context. Per-project isolation with automatic pruning.
344
+ ## Memory Backends
275
345
 
276
- Database: `agentContext/memories`
346
+ ### Desktop
277
347
 
278
- #### Long-term Memory (Cloud Backends)
348
+ - **Short-term**: SQLite (local file)
349
+ - **Long-term**: Qdrant (Docker) or Qdrant Cloud
279
350
 
280
- Requires environment variables for opt-in:
351
+ ### Web (claude.ai, factory.ai)
281
352
 
282
- **GitHub**:
283
- ```bash
284
- export GITHUB_TOKEN=your_token
285
- ```
353
+ - **Short-term**: IndexedDB (browser)
354
+ - **Long-term**: GitHub or Qdrant Cloud
286
355
 
287
- **Qdrant Cloud** (1GB free tier):
288
356
  ```bash
357
+ # Cloud backends (optional)
289
358
  export QDRANT_API_KEY=your_key
290
- export QDRANT_URL=https://xxxxx.aws.cloud.qdrant.io:6333
359
+ export QDRANT_URL=https://xxx.aws.cloud.qdrant.io:6333
360
+ export GITHUB_TOKEN=your_token
291
361
  ```
292
362
 
293
- ### What Memory Stores
363
+ ## Built-in Droids
294
364
 
295
- Vector database for semantic search of past learnings:
296
- - Discoveries about environment/capabilities
297
- - Successful strategies
298
- - Failed approaches to avoid
299
- - Important facts learned
365
+ | Droid | Purpose |
366
+ |-------|---------|
367
+ | `code-quality-guardian` | Code review, complexity, SOLID |
368
+ | `security-auditor` | OWASP, secrets, injection |
369
+ | `performance-optimizer` | Algorithms, memory, caching |
370
+ | `documentation-expert` | JSDoc, README, accuracy |
300
371
 
301
372
  ## Development
302
373
 
303
374
  ```bash
304
- # Clone and install
375
+ # Clone
305
376
  git clone https://github.com/DammianMiller/universal-agent-memory.git
306
377
  cd universal-agent-memory
378
+
379
+ # Install
307
380
  npm install
308
381
 
309
382
  # Build
310
383
  npm run build
311
384
 
312
- # Run locally
313
- npm start -- init
314
-
315
- # Run tests
385
+ # Test
316
386
  npm test
387
+
388
+ # Run locally
389
+ npm start -- init --interactive
317
390
  ```
318
391
 
392
+ ## Requirements
393
+
394
+ - Node.js 18+
395
+ - Docker (for local Qdrant)
396
+ - Git
397
+
319
398
  ## License
320
399
 
321
400
  MIT
401
+
402
+ ## Links
403
+
404
+ - [GitHub Repository](https://github.com/DammianMiller/universal-agent-memory)
405
+ - [npm Package](https://www.npmjs.com/package/universal-agent-memory)
406
+ - [Issue Tracker](https://github.com/DammianMiller/universal-agent-memory/issues)
package/dist/analyzers/index.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analyzers/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAoE1E"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analyzers/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAgF1E"}