agent-working-memory 0.3.0 → 0.3.2
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.
- package/README.md +84 -72
- package/dist/cli.js +29 -10
- package/dist/cli.js.map +1 -1
- package/package.json +1 -1
- package/src/cli.ts +30 -10
package/README.md
CHANGED
|
@@ -34,42 +34,104 @@ AWM is modeled on established cognitive science — ACT-R activation decay, Hebb
|
|
|
34
34
|
| Real-World | **93.1% EXCELLENT** | 300 code chunks from a 71K-line production monorepo |
|
|
35
35
|
| Token Savings | **64.5% savings** | Memory-guided context vs full conversation history |
|
|
36
36
|
|
|
37
|
-
##
|
|
37
|
+
## Quick Start — Claude Code (Recommended)
|
|
38
|
+
|
|
39
|
+
The fastest way to use AWM. Two commands, works in every project.
|
|
38
40
|
|
|
39
41
|
### Prerequisites
|
|
40
42
|
|
|
41
|
-
|
|
43
|
+
**Node.js 20+** — download from [nodejs.org](https://nodejs.org) if needed. Check with `node --version`.
|
|
44
|
+
|
|
45
|
+
### Install
|
|
42
46
|
|
|
43
|
-
|
|
47
|
+
```bash
|
|
48
|
+
npm install -g agent-working-memory
|
|
49
|
+
```
|
|
44
50
|
|
|
45
|
-
###
|
|
51
|
+
### Setup (Global — one brain for all projects)
|
|
46
52
|
|
|
47
53
|
```bash
|
|
48
|
-
|
|
49
|
-
cd AgentWorkingMemory
|
|
54
|
+
awm setup --global
|
|
50
55
|
```
|
|
51
56
|
|
|
52
|
-
|
|
57
|
+
This writes `~/.mcp.json` so Claude Code picks up AWM everywhere. One unified memory across all your work.
|
|
58
|
+
|
|
59
|
+
**Restart Claude Code** to load the MCP server. The first conversation will download three small ML models (~124MB, cached locally). After that, everything runs on your machine — no API keys, no cloud calls.
|
|
60
|
+
|
|
61
|
+
### Setup (Per-project)
|
|
62
|
+
|
|
63
|
+
If you prefer isolated memory per project instead:
|
|
53
64
|
|
|
54
65
|
```bash
|
|
55
|
-
|
|
66
|
+
cd your-project
|
|
67
|
+
awm setup
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
This creates `.mcp.json` in the current directory and appends workflow instructions to `CLAUDE.md`. Use `--agent-id my-project` to customize the agent identifier.
|
|
71
|
+
|
|
72
|
+
### What Claude gets
|
|
73
|
+
|
|
74
|
+
After restarting Claude Code, 11 memory tools appear automatically:
|
|
75
|
+
|
|
76
|
+
| Tool | What it does |
|
|
77
|
+
|------|-------------|
|
|
78
|
+
| `memory_write` | Store a memory with salience metadata |
|
|
79
|
+
| `memory_recall` | Retrieve relevant memories by context |
|
|
80
|
+
| `memory_feedback` | Tell AWM if a memory was useful or not |
|
|
81
|
+
| `memory_retract` | Mark a wrong memory as invalid |
|
|
82
|
+
| `memory_stats` | View memory health metrics |
|
|
83
|
+
| `memory_checkpoint` | Save execution state (survives context compaction) |
|
|
84
|
+
| `memory_restore` | Recover state + relevant context at conversation start |
|
|
85
|
+
| `memory_task_add` | Create a prioritized task |
|
|
86
|
+
| `memory_task_update` | Change task status/priority |
|
|
87
|
+
| `memory_task_list` | List tasks by status |
|
|
88
|
+
| `memory_task_next` | Get the highest-priority actionable task |
|
|
89
|
+
|
|
90
|
+
You don't need to tell Claude to "use memory." Once connected, Claude will automatically write important decisions, recall relevant context, and learn from feedback. Over time, it builds up knowledge that persists across every conversation.
|
|
91
|
+
|
|
92
|
+
### Optional: Add workflow instructions to CLAUDE.md
|
|
93
|
+
|
|
94
|
+
For per-project setups, `awm setup` does this automatically. For global setups, add this to any project's `CLAUDE.md` where you want explicit memory guidance:
|
|
95
|
+
|
|
96
|
+
```markdown
|
|
97
|
+
## Memory (AWM)
|
|
98
|
+
You have persistent memory via the agent-working-memory MCP server.
|
|
99
|
+
- At conversation start: call memory_restore to recover previous context
|
|
100
|
+
- When you learn something important: call memory_write
|
|
101
|
+
- When you need past context: call memory_recall
|
|
102
|
+
- Before long operations: call memory_checkpoint to save your state
|
|
103
|
+
- After using a recalled memory: call memory_feedback (useful/not-useful)
|
|
56
104
|
```
|
|
57
105
|
|
|
58
|
-
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## HTTP API (Alternative)
|
|
59
109
|
|
|
60
|
-
|
|
110
|
+
If you want to use AWM outside of Claude Code (custom agents, scripts, etc.), you can run the HTTP server directly.
|
|
111
|
+
|
|
112
|
+
### From npm
|
|
61
113
|
|
|
62
114
|
```bash
|
|
115
|
+
npm install -g agent-working-memory
|
|
116
|
+
awm serve
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### From source
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
git clone https://github.com/CompleteIdeas/agent-working-memory.git
|
|
123
|
+
cd agent-working-memory
|
|
124
|
+
npm install
|
|
63
125
|
npx tsx src/index.ts
|
|
64
126
|
```
|
|
65
127
|
|
|
66
|
-
**The first time you run this, it downloads three small ML models (~124MB total).** These are cached locally in a `models/` folder
|
|
128
|
+
**The first time you run this, it downloads three small ML models (~124MB total).** These are cached locally in a `models/` folder. No API keys, no cloud calls. Everything runs on your machine.
|
|
67
129
|
|
|
68
130
|
Once you see `AWM server listening on port 8400`, the server is ready.
|
|
69
131
|
|
|
70
|
-
###
|
|
132
|
+
### Try it
|
|
71
133
|
|
|
72
|
-
|
|
134
|
+
Write a memory:
|
|
73
135
|
|
|
74
136
|
```bash
|
|
75
137
|
curl -X POST http://localhost:8400/memory/write \
|
|
@@ -84,7 +146,7 @@ curl -X POST http://localhost:8400/memory/write \
|
|
|
84
146
|
}'
|
|
85
147
|
```
|
|
86
148
|
|
|
87
|
-
|
|
149
|
+
Recall it:
|
|
88
150
|
|
|
89
151
|
```bash
|
|
90
152
|
curl -X POST http://localhost:8400/memory/activate \
|
|
@@ -95,65 +157,15 @@ curl -X POST http://localhost:8400/memory/activate \
|
|
|
95
157
|
}'
|
|
96
158
|
```
|
|
97
159
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
### Tips for Technical People
|
|
101
|
-
|
|
102
|
-
- **Change the port:** `AWM_PORT=3000 npx tsx src/index.ts`
|
|
103
|
-
- **Custom database location:** `AWM_DB_PATH=/path/to/memory.db npx tsx src/index.ts`
|
|
104
|
-
- **Run unit tests:** `npx vitest run` (47 tests, no server needed)
|
|
105
|
-
- **Run eval suite:** Start the server first, then `npm run test:self` in another terminal
|
|
106
|
-
- **Data lives in a single file:** `memory.db` in the project root (SQLite). Back it up, move it, delete it to start fresh.
|
|
107
|
-
- **Models are cached locally:** First run downloads to `models/`. No network calls after that.
|
|
108
|
-
|
|
109
|
-
---
|
|
110
|
-
|
|
111
|
-
## Using with Claude Code (MCP Integration)
|
|
112
|
-
|
|
113
|
-
This is the main use case — giving Claude Code persistent memory across conversations. AWM connects to Claude Code through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), which lets Claude use AWM's memory tools directly.
|
|
114
|
-
|
|
115
|
-
### Step 1: Find your project's MCP config
|
|
116
|
-
|
|
117
|
-
In the project where you want Claude to have memory, create or edit `.mcp.json` in the project root:
|
|
118
|
-
|
|
119
|
-
```json
|
|
120
|
-
{
|
|
121
|
-
"mcpServers": {
|
|
122
|
-
"agent-working-memory": {
|
|
123
|
-
"command": "npx",
|
|
124
|
-
"args": ["tsx", "C:/path/to/AgentWorkingMemory/src/mcp.ts"],
|
|
125
|
-
"env": {
|
|
126
|
-
"AWM_DB_PATH": "C:/path/to/memory.db",
|
|
127
|
-
"AWM_AGENT_ID": "claude-code"
|
|
128
|
-
}
|
|
129
|
-
}
|
|
130
|
-
}
|
|
131
|
-
}
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
**Replace the paths** with the actual location where you cloned AgentWorkingMemory. Use forward slashes even on Windows.
|
|
135
|
-
|
|
136
|
-
### Step 2: Restart Claude Code
|
|
137
|
-
|
|
138
|
-
Close and reopen Claude Code (or run `/mcp` to reload). Claude will now have 9 new tools:
|
|
139
|
-
|
|
140
|
-
| Tool | What it does |
|
|
141
|
-
|------|-------------|
|
|
142
|
-
| `memory_write` | Store a memory with salience metadata |
|
|
143
|
-
| `memory_recall` | Retrieve relevant memories by context |
|
|
144
|
-
| `memory_feedback` | Tell AWM if a memory was useful or not |
|
|
145
|
-
| `memory_retract` | Mark a wrong memory as invalid |
|
|
146
|
-
| `memory_stats` | View memory health metrics |
|
|
147
|
-
| `memory_task_add` | Create a prioritized task |
|
|
148
|
-
| `memory_task_update` | Change task status/priority |
|
|
149
|
-
| `memory_task_list` | List tasks by status |
|
|
150
|
-
| `memory_task_next` | Get the highest-priority actionable task |
|
|
151
|
-
|
|
152
|
-
### Step 3: Use it naturally
|
|
153
|
-
|
|
154
|
-
You don't need to tell Claude to "use memory." Once MCP is connected, Claude will automatically write important decisions, recall relevant context, and learn from feedback. Over time, it builds up project knowledge that persists across every conversation.
|
|
160
|
+
### Configuration
|
|
155
161
|
|
|
156
|
-
**
|
|
162
|
+
- **Change the port:** `awm serve --port 3000` or `AWM_PORT=3000`
|
|
163
|
+
- **Custom database:** `AWM_DB_PATH=/path/to/memory.db`
|
|
164
|
+
- **API key auth:** Set `AWM_API_KEY=your-secret` in `.env` — requests need `Authorization: Bearer your-secret` or `x-api-key: your-secret`
|
|
165
|
+
- **Run tests:** `npx vitest run` (65 tests)
|
|
166
|
+
- **Run eval suite:** `npm run test:self`
|
|
167
|
+
- **Data is a single file:** `data/memory.db` (SQLite). Back it up, move it, delete it to start fresh.
|
|
168
|
+
- **Models cached locally:** First run downloads to `models/`. No network after that.
|
|
157
169
|
|
|
158
170
|
---
|
|
159
171
|
|
package/dist/cli.js
CHANGED
|
@@ -12,6 +12,7 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
|
|
|
12
12
|
import { resolve, basename, join, dirname } from 'node:path';
|
|
13
13
|
import { execSync } from 'node:child_process';
|
|
14
14
|
import { fileURLToPath } from 'node:url';
|
|
15
|
+
import { homedir as osHomedir } from 'node:os';
|
|
15
16
|
const __filename = fileURLToPath(import.meta.url);
|
|
16
17
|
const __dirname = dirname(__filename);
|
|
17
18
|
// Load .env if present
|
|
@@ -39,16 +40,18 @@ function printUsage() {
|
|
|
39
40
|
AgentWorkingMemory — Cognitive memory for AI agents
|
|
40
41
|
|
|
41
42
|
Usage:
|
|
42
|
-
awm setup [--agent-id <id>] [--db-path <path>] [--no-claude-md]
|
|
43
|
-
Configure MCP for
|
|
43
|
+
awm setup [--global] [--agent-id <id>] [--db-path <path>] [--no-claude-md]
|
|
44
|
+
Configure MCP for Claude Code
|
|
44
45
|
awm mcp Start MCP server (used by Claude Code)
|
|
45
46
|
awm serve [--port <port>] Start HTTP API server
|
|
46
47
|
awm health [--port <port>] Check server health
|
|
47
48
|
|
|
48
49
|
Setup:
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
50
|
+
awm setup --global Recommended. Writes ~/.mcp.json so AWM is available
|
|
51
|
+
in every project — one brain across all your work.
|
|
52
|
+
|
|
53
|
+
awm setup Project-level. Writes .mcp.json in the current directory
|
|
54
|
+
and appends workflow instructions to CLAUDE.md.
|
|
52
55
|
|
|
53
56
|
Use --no-claude-md to skip CLAUDE.md modification.
|
|
54
57
|
Restart Claude Code after setup to pick up the new MCP server.
|
|
@@ -62,6 +65,7 @@ function setup() {
|
|
|
62
65
|
let agentId = projectName;
|
|
63
66
|
let dbPath = null;
|
|
64
67
|
let skipClaudeMd = false;
|
|
68
|
+
let isGlobal = false;
|
|
65
69
|
for (let i = 1; i < args.length; i++) {
|
|
66
70
|
if (args[i] === '--agent-id' && args[i + 1]) {
|
|
67
71
|
agentId = args[++i];
|
|
@@ -72,6 +76,10 @@ function setup() {
|
|
|
72
76
|
else if (args[i] === '--no-claude-md') {
|
|
73
77
|
skipClaudeMd = true;
|
|
74
78
|
}
|
|
79
|
+
else if (args[i] === '--global') {
|
|
80
|
+
isGlobal = true;
|
|
81
|
+
agentId = 'claude'; // unified agent ID for global setup
|
|
82
|
+
}
|
|
75
83
|
}
|
|
76
84
|
// Find the package root (where src/mcp.ts lives)
|
|
77
85
|
const packageRoot = resolve(__dirname, '..');
|
|
@@ -123,7 +131,7 @@ function setup() {
|
|
|
123
131
|
};
|
|
124
132
|
}
|
|
125
133
|
// Read or create .mcp.json
|
|
126
|
-
const mcpJsonPath = join(cwd, '.mcp.json');
|
|
134
|
+
const mcpJsonPath = isGlobal ? join(osHomedir(), '.mcp.json') : join(cwd, '.mcp.json');
|
|
127
135
|
let existing = { mcpServers: {} };
|
|
128
136
|
if (existsSync(mcpJsonPath)) {
|
|
129
137
|
try {
|
|
@@ -151,7 +159,16 @@ You have persistent memory via the agent-working-memory MCP server.
|
|
|
151
159
|
- To retract incorrect info: call memory_retract
|
|
152
160
|
- To manage tasks: call memory_task_add, memory_task_update, memory_task_list, memory_task_next
|
|
153
161
|
`;
|
|
154
|
-
|
|
162
|
+
// For global: write to ~/.claude/CLAUDE.md (loaded by Claude Code in every session)
|
|
163
|
+
// For project: write to ./CLAUDE.md in the current directory
|
|
164
|
+
const claudeMdPath = isGlobal
|
|
165
|
+
? join(osHomedir(), '.claude', 'CLAUDE.md')
|
|
166
|
+
: join(cwd, 'CLAUDE.md');
|
|
167
|
+
// Ensure parent directory exists (for ~/.claude/CLAUDE.md)
|
|
168
|
+
const claudeMdDir = dirname(claudeMdPath);
|
|
169
|
+
if (!existsSync(claudeMdDir)) {
|
|
170
|
+
mkdirSync(claudeMdDir, { recursive: true });
|
|
171
|
+
}
|
|
155
172
|
if (skipClaudeMd) {
|
|
156
173
|
claudeMdAction = ' CLAUDE.md: skipped (--no-claude-md)';
|
|
157
174
|
}
|
|
@@ -166,11 +183,13 @@ You have persistent memory via the agent-working-memory MCP server.
|
|
|
166
183
|
}
|
|
167
184
|
}
|
|
168
185
|
else {
|
|
169
|
-
|
|
186
|
+
const title = isGlobal ? '# Global Instructions' : `# ${basename(cwd)}`;
|
|
187
|
+
writeFileSync(claudeMdPath, `${title}\n${claudeMdSnippet}`);
|
|
170
188
|
claudeMdAction = ' CLAUDE.md: created with AWM workflow section';
|
|
171
189
|
}
|
|
190
|
+
const scope = isGlobal ? 'globally (all projects)' : cwd;
|
|
172
191
|
console.log(`
|
|
173
|
-
AWM configured for:
|
|
192
|
+
AWM configured ${isGlobal ? 'globally' : 'for: ' + cwd}
|
|
174
193
|
|
|
175
194
|
Agent ID: ${agentId}
|
|
176
195
|
DB path: ${dbPath}
|
|
@@ -179,7 +198,7 @@ ${claudeMdAction}
|
|
|
179
198
|
|
|
180
199
|
Next steps:
|
|
181
200
|
1. Restart Claude Code to pick up the MCP server
|
|
182
|
-
2. The memory tools will appear automatically
|
|
201
|
+
2. The memory tools will appear automatically${isGlobal ? '\n 3. One brain across all your projects — no per-project setup needed' : ''}
|
|
183
202
|
`.trim());
|
|
184
203
|
}
|
|
185
204
|
// ─── MCP ──────────────────────────────────────
|
package/dist/cli.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;
|
|
1
|
+
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
package/src/cli.ts
CHANGED
|
@@ -14,6 +14,7 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
|
|
|
14
14
|
import { resolve, basename, join, dirname } from 'node:path';
|
|
15
15
|
import { execSync } from 'node:child_process';
|
|
16
16
|
import { fileURLToPath } from 'node:url';
|
|
17
|
+
import { homedir as osHomedir } from 'node:os';
|
|
17
18
|
|
|
18
19
|
const __filename = fileURLToPath(import.meta.url);
|
|
19
20
|
const __dirname = dirname(__filename);
|
|
@@ -41,16 +42,18 @@ function printUsage() {
|
|
|
41
42
|
AgentWorkingMemory — Cognitive memory for AI agents
|
|
42
43
|
|
|
43
44
|
Usage:
|
|
44
|
-
awm setup [--agent-id <id>] [--db-path <path>] [--no-claude-md]
|
|
45
|
-
Configure MCP for
|
|
45
|
+
awm setup [--global] [--agent-id <id>] [--db-path <path>] [--no-claude-md]
|
|
46
|
+
Configure MCP for Claude Code
|
|
46
47
|
awm mcp Start MCP server (used by Claude Code)
|
|
47
48
|
awm serve [--port <port>] Start HTTP API server
|
|
48
49
|
awm health [--port <port>] Check server health
|
|
49
50
|
|
|
50
51
|
Setup:
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
52
|
+
awm setup --global Recommended. Writes ~/.mcp.json so AWM is available
|
|
53
|
+
in every project — one brain across all your work.
|
|
54
|
+
|
|
55
|
+
awm setup Project-level. Writes .mcp.json in the current directory
|
|
56
|
+
and appends workflow instructions to CLAUDE.md.
|
|
54
57
|
|
|
55
58
|
Use --no-claude-md to skip CLAUDE.md modification.
|
|
56
59
|
Restart Claude Code after setup to pick up the new MCP server.
|
|
@@ -67,6 +70,7 @@ function setup() {
|
|
|
67
70
|
let agentId = projectName;
|
|
68
71
|
let dbPath: string | null = null;
|
|
69
72
|
let skipClaudeMd = false;
|
|
73
|
+
let isGlobal = false;
|
|
70
74
|
|
|
71
75
|
for (let i = 1; i < args.length; i++) {
|
|
72
76
|
if (args[i] === '--agent-id' && args[i + 1]) {
|
|
@@ -75,6 +79,9 @@ function setup() {
|
|
|
75
79
|
dbPath = args[++i];
|
|
76
80
|
} else if (args[i] === '--no-claude-md') {
|
|
77
81
|
skipClaudeMd = true;
|
|
82
|
+
} else if (args[i] === '--global') {
|
|
83
|
+
isGlobal = true;
|
|
84
|
+
agentId = 'claude'; // unified agent ID for global setup
|
|
78
85
|
}
|
|
79
86
|
}
|
|
80
87
|
|
|
@@ -132,7 +139,7 @@ function setup() {
|
|
|
132
139
|
}
|
|
133
140
|
|
|
134
141
|
// Read or create .mcp.json
|
|
135
|
-
const mcpJsonPath = join(cwd, '.mcp.json');
|
|
142
|
+
const mcpJsonPath = isGlobal ? join(osHomedir(), '.mcp.json') : join(cwd, '.mcp.json');
|
|
136
143
|
let existing: any = { mcpServers: {} };
|
|
137
144
|
if (existsSync(mcpJsonPath)) {
|
|
138
145
|
try {
|
|
@@ -161,7 +168,18 @@ You have persistent memory via the agent-working-memory MCP server.
|
|
|
161
168
|
- To manage tasks: call memory_task_add, memory_task_update, memory_task_list, memory_task_next
|
|
162
169
|
`;
|
|
163
170
|
|
|
164
|
-
|
|
171
|
+
// For global: write to ~/.claude/CLAUDE.md (loaded by Claude Code in every session)
|
|
172
|
+
// For project: write to ./CLAUDE.md in the current directory
|
|
173
|
+
const claudeMdPath = isGlobal
|
|
174
|
+
? join(osHomedir(), '.claude', 'CLAUDE.md')
|
|
175
|
+
: join(cwd, 'CLAUDE.md');
|
|
176
|
+
|
|
177
|
+
// Ensure parent directory exists (for ~/.claude/CLAUDE.md)
|
|
178
|
+
const claudeMdDir = dirname(claudeMdPath);
|
|
179
|
+
if (!existsSync(claudeMdDir)) {
|
|
180
|
+
mkdirSync(claudeMdDir, { recursive: true });
|
|
181
|
+
}
|
|
182
|
+
|
|
165
183
|
if (skipClaudeMd) {
|
|
166
184
|
claudeMdAction = ' CLAUDE.md: skipped (--no-claude-md)';
|
|
167
185
|
} else if (existsSync(claudeMdPath)) {
|
|
@@ -173,12 +191,14 @@ You have persistent memory via the agent-working-memory MCP server.
|
|
|
173
191
|
claudeMdAction = ' CLAUDE.md: appended AWM workflow section';
|
|
174
192
|
}
|
|
175
193
|
} else {
|
|
176
|
-
|
|
194
|
+
const title = isGlobal ? '# Global Instructions' : `# ${basename(cwd)}`;
|
|
195
|
+
writeFileSync(claudeMdPath, `${title}\n${claudeMdSnippet}`);
|
|
177
196
|
claudeMdAction = ' CLAUDE.md: created with AWM workflow section';
|
|
178
197
|
}
|
|
179
198
|
|
|
199
|
+
const scope = isGlobal ? 'globally (all projects)' : cwd;
|
|
180
200
|
console.log(`
|
|
181
|
-
AWM configured for:
|
|
201
|
+
AWM configured ${isGlobal ? 'globally' : 'for: ' + cwd}
|
|
182
202
|
|
|
183
203
|
Agent ID: ${agentId}
|
|
184
204
|
DB path: ${dbPath}
|
|
@@ -187,7 +207,7 @@ ${claudeMdAction}
|
|
|
187
207
|
|
|
188
208
|
Next steps:
|
|
189
209
|
1. Restart Claude Code to pick up the MCP server
|
|
190
|
-
2. The memory tools will appear automatically
|
|
210
|
+
2. The memory tools will appear automatically${isGlobal ? '\n 3. One brain across all your projects — no per-project setup needed' : ''}
|
|
191
211
|
`.trim());
|
|
192
212
|
}
|
|
193
213
|
|