neuronlayer 0.2.7 → 0.2.8

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.
@@ -0,0 +1,504 @@
1
+ # MemoryLayer + Claude Code Setup Guide
2
+
3
+ This guide explains how to configure MemoryLayer as an MCP server for [Claude Code](https://code.claude.com/) (Anthropic's CLI tool).
4
+
5
+ ---
6
+
7
+ ## Prerequisites
8
+
9
+ 1. **Node.js 18+** installed
10
+ 2. **Claude Code** installed (`npm install -g @anthropic-ai/claude-code`)
11
+ 3. **MemoryLayer** built (`npm run build`)
12
+
13
+ ---
14
+
15
+ ## Quick Setup (Recommended)
16
+
17
+ The easiest and most reliable way to configure MemoryLayer for Claude Code is using our automated initialization command.
18
+
19
+ ### Step 1: Initialize MemoryLayer
20
+
21
+ Run this command in the root of your project:
22
+
23
+ ```bash
24
+ npx neuronlayer init .
25
+ ```
26
+
27
+ This will automatically configure `.mcp.json` in your project with the exact absolute paths and platform-specific commands required for Claude Code to connect smoothly to MemoryLayer.
28
+
29
+ ### Step 2: Verify Connection
30
+
31
+ Start Claude Code and check your servers:
32
+
33
+ ```bash
34
+ # Inside Claude Code
35
+ /mcp
36
+ ```
37
+
38
+ You should see:
39
+ ```
40
+ MCP Servers
41
+ neuronlayer (stdio)
42
+ Status: connected
43
+ ```
44
+
45
+ ---
46
+
47
+ ## Configuration Methods (Advanced)
48
+
49
+ If you prefer not to use the automated `npx neuronlayer init` command, Claude Code provides several ways to configure MCP servers manually.
50
+
51
+ ### Method 1: CLI Commands
52
+
53
+ Claude Code provides CLI commands to manage MCP servers:
54
+
55
+ ```bash
56
+ # Add a server
57
+ claude mcp add --transport stdio neuronlayer -- node /absolute/path/to/dist/index.js --project .
58
+
59
+ # List all servers
60
+ claude mcp list
61
+
62
+ # Get server details
63
+ claude mcp get neuronlayer
64
+
65
+ # Remove a server
66
+ claude mcp remove neuronlayer
67
+ ```
68
+
69
+ **Note:** On Windows natively, you MUST wrap the node execution with `cmd /c` to prevent stdin/stdout hanging issues:
70
+ ```bash
71
+ claude mcp add --transport stdio neuronlayer -- cmd /c node C:\absolute\path\to\dist\index.js --project .
72
+ ```
73
+
74
+ ### Method 2: Project Configuration (`.mcp.json`)
75
+
76
+ If you want to create `.mcp.json` in your project root manually:
77
+
78
+ ```json
79
+ {
80
+ "mcpServers": {
81
+ "neuronlayer": {
82
+ "type": "stdio",
83
+ "command": "node",
84
+ "args": ["/absolute/path/to/memorylayer/dist/index.js", "--project", "."],
85
+ "env": {}
86
+ }
87
+ }
88
+ }
89
+ ```
90
+
91
+ *For Windows, use `["cmd", "/c", "node", "C:\\absolute\\path\\to\\dist\\index.js", "--project", "."]` in the command and args fields as appropriate depending on your node integration.*
92
+
93
+ ---
94
+
95
+ ## Configuration Scopes
96
+
97
+ | Scope | Storage Location | Use Case |
98
+ |-------|------------------|----------|
99
+ | `local` (default) | `~/.claude.json` | Personal, current project only |
100
+ | `project` | `.mcp.json` | Shared with team via version control |
101
+ | `user` | `~/.claude.json` | Personal, available across all projects |
102
+
103
+ ```bash
104
+ # The automated init command uses Project scope by default
105
+ npx neuronlayer init .
106
+ ```
107
+
108
+ ---
109
+
110
+ ## Platform-Specific Setup
111
+
112
+ ### Windows (Native)
113
+
114
+ On native Windows (not WSL), use the `cmd /c` wrapper for proper execution:
115
+
116
+ ```bash
117
+ # Using CLI
118
+ claude mcp add --transport stdio memorylayer -- cmd /c node C:\path\to\memorylayer\dist\index.js --project .
119
+ ```
120
+
121
+ **In `.mcp.json`:**
122
+
123
+ ```json
124
+ {
125
+ "mcpServers": {
126
+ "memorylayer": {
127
+ "type": "stdio",
128
+ "command": "cmd",
129
+ "args": ["/c", "node", "C:\\path\\to\\memorylayer\\dist\\index.js", "--project", "."],
130
+ "env": {}
131
+ }
132
+ }
133
+ }
134
+ ```
135
+
136
+ ### Windows (WSL)
137
+
138
+ WSL works like Linux:
139
+
140
+ ```bash
141
+ claude mcp add --transport stdio memorylayer -- node /path/to/memorylayer/dist/index.js --project .
142
+ ```
143
+
144
+ ### macOS / Linux
145
+
146
+ ```bash
147
+ claude mcp add --transport stdio memorylayer -- node /path/to/memorylayer/dist/index.js --project .
148
+ ```
149
+
150
+ **In `.mcp.json`:**
151
+
152
+ ```json
153
+ {
154
+ "mcpServers": {
155
+ "memorylayer": {
156
+ "type": "stdio",
157
+ "command": "node",
158
+ "args": ["/Users/you/memorylayer/dist/index.js", "--project", "."],
159
+ "env": {}
160
+ }
161
+ }
162
+ }
163
+ ```
164
+
165
+ ---
166
+
167
+ ## After npm Publish
168
+
169
+ Once MemoryLayer is published to npm, setup becomes simpler:
170
+
171
+ ### CLI Command
172
+
173
+ ```bash
174
+ # Install globally
175
+ npm install -g memorylayer
176
+
177
+ # Add to Claude Code
178
+ claude mcp add --transport stdio memorylayer -- memorylayer --project .
179
+ ```
180
+
181
+ ### Using npx
182
+
183
+ ```bash
184
+ # Without installation
185
+ claude mcp add --transport stdio memorylayer -- npx -y memorylayer --project .
186
+ ```
187
+
188
+ **Windows (with npx):**
189
+
190
+ ```bash
191
+ claude mcp add --transport stdio memorylayer -- cmd /c npx -y memorylayer --project .
192
+ ```
193
+
194
+ ### Project `.mcp.json`
195
+
196
+ ```json
197
+ {
198
+ "mcpServers": {
199
+ "memorylayer": {
200
+ "type": "stdio",
201
+ "command": "npx",
202
+ "args": ["-y", "memorylayer", "--project", "."],
203
+ "env": {}
204
+ }
205
+ }
206
+ }
207
+ ```
208
+
209
+ ---
210
+
211
+ ## Environment Variables
212
+
213
+ ### MemoryLayer Configuration
214
+
215
+ | Variable | Default | Description |
216
+ |----------|---------|-------------|
217
+ | `MEMORYLAYER_MAX_TOKENS` | 6000 | Maximum tokens for context assembly |
218
+ | `MEMORYLAYER_DEBUG` | false | Enable debug logging |
219
+
220
+ ```bash
221
+ claude mcp add --transport stdio \
222
+ --env MEMORYLAYER_MAX_TOKENS=8000 \
223
+ --env MEMORYLAYER_DEBUG=true \
224
+ memorylayer -- node dist/index.js --project .
225
+ ```
226
+
227
+ ### Claude Code MCP Settings
228
+
229
+ | Variable | Default | Description |
230
+ |----------|---------|-------------|
231
+ | `MCP_TIMEOUT` | 60000 | Server startup timeout (ms) |
232
+ | `MAX_MCP_OUTPUT_TOKENS` | 25000 | Max tokens from MCP tools |
233
+
234
+ ```bash
235
+ # Start Claude Code with custom MCP settings
236
+ MCP_TIMEOUT=120000 MAX_MCP_OUTPUT_TOKENS=50000 claude
237
+ ```
238
+
239
+ ---
240
+
241
+ ## Available MCP Tools
242
+
243
+ Once connected, Claude Code can use these MemoryLayer tools:
244
+
245
+ ### Core Tools
246
+
247
+ | Tool | Description |
248
+ |------|-------------|
249
+ | `get_context` | Get relevant codebase context for a query |
250
+ | `search_codebase` | Semantic search across all files |
251
+ | `record_decision` | Save an architectural decision |
252
+ | `get_file_context` | Get content of a specific file |
253
+ | `get_project_summary` | Overview of project structure |
254
+
255
+ ### Symbol & Dependency Tools
256
+
257
+ | Tool | Description |
258
+ |------|-------------|
259
+ | `get_symbol` | Find functions, classes, types by name |
260
+ | `get_dependencies` | See imports/exports for a file |
261
+ | `get_file_summary` | Get compressed file summary (10x smaller) |
262
+
263
+ ### Living Documentation Tools
264
+
265
+ | Tool | Description |
266
+ |------|-------------|
267
+ | `generate_docs` | Generate documentation for a file or architecture |
268
+ | `get_architecture` | Get project architecture overview |
269
+ | `get_component_doc` | Get detailed documentation for a component |
270
+ | `get_changelog` | Get changelog of recent changes |
271
+ | `validate_docs` | Check for outdated docs |
272
+ | `what_happened` | Query recent project activity |
273
+
274
+ ### Context Health Tools
275
+
276
+ | Tool | Description |
277
+ |------|-------------|
278
+ | `get_context_health` | Check context health and drift score |
279
+ | `trigger_compaction` | Manually trigger context compaction |
280
+ | `mark_critical` | Mark content as critical (never compress) |
281
+
282
+ ### Confidence & Intelligence Tools
283
+
284
+ | Tool | Description |
285
+ |------|-------------|
286
+ | `get_confidence` | Get confidence score for code suggestion |
287
+ | `check_conflicts` | Check if code conflicts with past decisions |
288
+ | `what_changed` | Query what changed in the codebase |
289
+ | `why_broke` | Diagnose why something broke |
290
+ | `suggest_fix` | Get fix suggestions for an error |
291
+
292
+ ### Architecture Tools
293
+
294
+ | Tool | Description |
295
+ |------|-------------|
296
+ | `validate_pattern` | Validate code against established patterns |
297
+ | `suggest_existing` | Find existing functions that match intent |
298
+ | `learn_pattern` | Teach a new pattern to the system |
299
+ | `list_patterns` | List all learned patterns |
300
+
301
+ ### Test Awareness Tools
302
+
303
+ | Tool | Description |
304
+ |------|-------------|
305
+ | `get_related_tests` | Get tests related to a file or function |
306
+ | `check_tests` | Check if a code change would break tests |
307
+ | `suggest_test_update` | Get suggested test updates for a change |
308
+ | `get_test_coverage` | Get test coverage for a file |
309
+
310
+ ---
311
+
312
+ ## Example Usage
313
+
314
+ Once configured, try these prompts in Claude Code:
315
+
316
+ ```
317
+ > Search for authentication code in this project
318
+
319
+ > What architectural decisions have been made?
320
+
321
+ > Show me the project summary
322
+
323
+ > Find the function that handles user login
324
+
325
+ > What files import the database module?
326
+
327
+ > What changed in the last 24 hours?
328
+
329
+ > Why might the login test be failing?
330
+
331
+ > Record a decision: We chose SQLite for local storage because it's embedded and requires no separate server
332
+
333
+ > Get the architecture overview of this project
334
+
335
+ > Check if this code follows our patterns: async function fetchUser(id) { ... }
336
+ ```
337
+
338
+ ---
339
+
340
+ ## Troubleshooting
341
+
342
+ ### "Connection closed" on Windows
343
+
344
+ Ensure you're using the `cmd /c` wrapper:
345
+
346
+ ```bash
347
+ # Wrong
348
+ claude mcp add --transport stdio memorylayer -- node dist/index.js --project .
349
+
350
+ # Correct
351
+ claude mcp add --transport stdio memorylayer -- cmd /c node dist/index.js --project .
352
+ ```
353
+
354
+ ### "Server not found" or "ENOENT"
355
+
356
+ 1. Verify the path to `dist/index.js` is correct and absolute
357
+ 2. Ensure MemoryLayer is built: `npm run build`
358
+ 3. Check Node.js is in your PATH
359
+
360
+ ### "MCP server not connected"
361
+
362
+ 1. Run `claude mcp list` to check configuration
363
+ 2. Run `/mcp` inside Claude Code to see status
364
+ 3. Check for errors in the server output
365
+
366
+ ### "Configuration is invalid"
367
+
368
+ Ensure your JSON is valid and `command` is a string (not array):
369
+
370
+ ```json
371
+ // Correct
372
+ {
373
+ "type": "stdio",
374
+ "command": "node",
375
+ "args": ["dist/index.js", "--project", "."]
376
+ }
377
+
378
+ // Wrong
379
+ {
380
+ "type": "stdio",
381
+ "command": ["node", "dist/index.js"]
382
+ }
383
+ ```
384
+
385
+ ### Server Takes Too Long to Start
386
+
387
+ Increase the MCP timeout:
388
+
389
+ ```bash
390
+ MCP_TIMEOUT=120000 claude
391
+ ```
392
+
393
+ Or set in `.mcp.json`:
394
+
395
+ ```json
396
+ {
397
+ "mcpServers": {
398
+ "memorylayer": {
399
+ "type": "stdio",
400
+ "command": "node",
401
+ "args": ["dist/index.js", "--project", "."],
402
+ "env": {},
403
+ "timeout": 120000
404
+ }
405
+ }
406
+ }
407
+ ```
408
+
409
+ ### View Debug Logs
410
+
411
+ ```bash
412
+ # Run Claude Code with debug logging
413
+ claude --log-level DEBUG
414
+ ```
415
+
416
+ ---
417
+
418
+ ## Importing from Claude Desktop
419
+
420
+ If you already have MemoryLayer configured in Claude Desktop:
421
+
422
+ ```bash
423
+ # Import all servers from Claude Desktop
424
+ claude mcp add-from-claude-desktop
425
+
426
+ # Select memorylayer from the list
427
+
428
+ # Verify import
429
+ claude mcp list
430
+ ```
431
+
432
+ ---
433
+
434
+ ## Data Storage
435
+
436
+ MemoryLayer stores data locally:
437
+
438
+ ```
439
+ ~/.memorylayer/
440
+ ├── registry.json # Project registry
441
+ └── projects/
442
+ └── {project-name}-{hash}/
443
+ ├── memorylayer.db # SQLite database
444
+ └── tier1.json # Working context
445
+ ```
446
+
447
+ ---
448
+
449
+ ## Comparison: Claude Desktop vs Claude Code
450
+
451
+ | Feature | Claude Desktop | Claude Code |
452
+ |---------|----------------|-------------|
453
+ | Config Location | `~/.claude/claude_desktop_config.json` | `~/.claude.json` or `.mcp.json` |
454
+ | Add Server | Manual JSON edit | CLI commands or JSON |
455
+ | Project Scope | No | Yes (`.mcp.json`) |
456
+ | User Scope | Yes | Yes |
457
+ | Local Scope | N/A | Yes (default) |
458
+ | Env Var Expansion | No | Yes (`${VAR}` syntax) |
459
+
460
+ ---
461
+
462
+ ## Links
463
+
464
+ - [Claude Code Documentation](https://code.claude.com/docs/)
465
+ - [Claude Code MCP Guide](https://code.claude.com/docs/en/mcp)
466
+ - [Claude Code Settings](https://code.claude.com/docs/en/settings)
467
+ - [MCP Protocol Specification](https://modelcontextprotocol.io/)
468
+ - [MemoryLayer Documentation](./INDEX.md)
469
+
470
+ ---
471
+
472
+ ## Quick Reference
473
+
474
+ ### Minimum Setup
475
+
476
+ ```bash
477
+ # One-liner setup
478
+ claude mcp add --transport stdio memorylayer -- node /path/to/memorylayer/dist/index.js --project .
479
+ ```
480
+
481
+ ### Full `.mcp.json` Example
482
+
483
+ ```json
484
+ {
485
+ "mcpServers": {
486
+ "memorylayer": {
487
+ "type": "stdio",
488
+ "command": "node",
489
+ "args": [
490
+ "/path/to/memorylayer/dist/index.js",
491
+ "--project",
492
+ "."
493
+ ],
494
+ "env": {
495
+ "MEMORYLAYER_MAX_TOKENS": "8000"
496
+ }
497
+ }
498
+ }
499
+ }
500
+ ```
501
+
502
+ ---
503
+
504
+ *Last updated: February 2026*
@@ -0,0 +1,425 @@
1
+ # MemoryLayer + OpenCode Setup Guide
2
+
3
+ This guide explains how to configure MemoryLayer as an MCP server for [OpenCode](https://opencode.ai).
4
+
5
+ ---
6
+
7
+ ## Prerequisites
8
+
9
+ 1. **Node.js 18+** installed
10
+ 2. **OpenCode** installed (`npm install -g opencode`)
11
+ 3. **MemoryLayer** built (`npm run build`)
12
+
13
+ ---
14
+
15
+ ## Quick Setup (Recommended)
16
+
17
+ The easiest and most reliable way to configure MemoryLayer for OpenCode is using our automated initialization command.
18
+
19
+ ### Step 1: Initialize MemoryLayer
20
+
21
+ Run this command in the root of your project:
22
+
23
+ ```bash
24
+ npx neuronlayer init .
25
+ ```
26
+
27
+ This will automatically detect your operating system and generate the correct `opencode.json` configuration file with the exact absolute paths required for OpenCode to connect to MemoryLayer.
28
+
29
+ ### Step 2: Start OpenCode
30
+
31
+ ```bash
32
+ opencode
33
+ ```
34
+
35
+ ### Step 3: Verify Connection
36
+
37
+ Inside OpenCode, type:
38
+ ```
39
+ /mcp
40
+ ```
41
+
42
+ You should see:
43
+ ```
44
+ MCP Servers
45
+ neuronlayer (local)
46
+ Status: connected
47
+ ```
48
+
49
+ Or from your terminal:
50
+ ```bash
51
+ opencode mcp list
52
+ ```
53
+
54
+ ---
55
+
56
+ ## Manual Configuration (Advanced)
57
+
58
+ If you prefer to configure OpenCode manually, create an `opencode.json` file in your project root.
59
+
60
+ **IMPORTANT:** You must use **absolute paths** for reliable operation, and on Windows you must use `cmd` to wrap the Node execution.
61
+
62
+ **Windows Example:**
63
+ ```json
64
+ {
65
+ "$schema": "https://opencode.ai/config.json",
66
+ "mcp": {
67
+ "neuronlayer": {
68
+ "type": "local",
69
+ "command": ["cmd", "/c", "node", "C:\\Users\\YOUR_USERNAME\\path\\to\\memorylayer\\dist\\index.js", "--project", "C:\\Users\\YOUR_USERNAME\\path\\to\\your\\project"],
70
+ "enabled": true
71
+ }
72
+ }
73
+ }
74
+ ```
75
+
76
+ **macOS/Linux Example:**
77
+ ```json
78
+ {
79
+ "$schema": "https://opencode.ai/config.json",
80
+ "mcp": {
81
+ "neuronlayer": {
82
+ "type": "local",
83
+ "command": ["node", "/home/user/memorylayer/dist/index.js", "--project", "/home/user/myproject"],
84
+ "enabled": true
85
+ }
86
+ }
87
+ }
88
+ ```
89
+
90
+ ---
91
+
92
+ ## Global Setup
93
+
94
+ For system-wide availability, create the config in your home directory:
95
+
96
+ **Windows:** `%USERPROFILE%\.config\opencode\opencode.json`
97
+ **macOS/Linux:** `~/.config/opencode/opencode.json`
98
+
99
+ ```json
100
+ {
101
+ "$schema": "https://opencode.ai/config.json",
102
+ "mcp": {
103
+ "memorylayer": {
104
+ "type": "local",
105
+ "command": ["node", "/absolute/path/to/memorylayer/dist/index.js", "--project", "."],
106
+ "enabled": true
107
+ }
108
+ }
109
+ }
110
+ ```
111
+
112
+ ---
113
+
114
+ ## After npm Publish
115
+
116
+ Once MemoryLayer is published to npm, setup becomes simpler:
117
+
118
+ ### Using npx
119
+
120
+ ```json
121
+ {
122
+ "$schema": "https://opencode.ai/config.json",
123
+ "mcp": {
124
+ "memorylayer": {
125
+ "type": "local",
126
+ "command": ["npx", "-y", "memorylayer", "--project", "."],
127
+ "enabled": true
128
+ }
129
+ }
130
+ }
131
+ ```
132
+
133
+ ### Global Install
134
+
135
+ ```bash
136
+ npm install -g memorylayer
137
+ ```
138
+
139
+ ```json
140
+ {
141
+ "$schema": "https://opencode.ai/config.json",
142
+ "mcp": {
143
+ "memorylayer": {
144
+ "type": "local",
145
+ "command": ["memorylayer", "--project", "."],
146
+ "enabled": true
147
+ }
148
+ }
149
+ }
150
+ ```
151
+
152
+ ---
153
+
154
+ ## Configuration Reference
155
+
156
+ | Field | Type | Required | Description |
157
+ |-------|------|----------|-------------|
158
+ | `type` | `"local"` \| `"remote"` | Yes | Server type |
159
+ | `command` | `string[]` | Yes (local) | Command array (NOT a string) |
160
+ | `enabled` | `boolean` | Yes | Must be `true` to connect |
161
+ | `environment` | `object` | No | Environment variables |
162
+
163
+ ### Example with Environment Variables
164
+
165
+ ```json
166
+ {
167
+ "$schema": "https://opencode.ai/config.json",
168
+ "mcp": {
169
+ "memorylayer": {
170
+ "type": "local",
171
+ "command": ["node", "C:\\path\\to\\memorylayer\\dist\\index.js", "--project", "."],
172
+ "enabled": true,
173
+ "environment": {
174
+ "MEMORYLAYER_MAX_TOKENS": "8000",
175
+ "MEMORYLAYER_DEBUG": "true"
176
+ }
177
+ }
178
+ }
179
+ }
180
+ ```
181
+
182
+ ---
183
+
184
+ ## Available Tools (51 Total)
185
+
186
+ Once connected, OpenCode's AI can use all MemoryLayer tools:
187
+
188
+ ### Core Tools (5)
189
+ | Tool | Description |
190
+ |------|-------------|
191
+ | `get_context` | Get relevant codebase context for a query |
192
+ | `search_codebase` | Semantic search across all files |
193
+ | `record_decision` | Save an architectural decision |
194
+ | `get_file_context` | Get content of a specific file |
195
+ | `get_project_summary` | Overview of project structure |
196
+
197
+ ### Symbol & Dependency Tools (3)
198
+ | Tool | Description |
199
+ |------|-------------|
200
+ | `get_symbol` | Find functions, classes, types by name |
201
+ | `get_dependencies` | See imports/exports for a file |
202
+ | `get_file_summary` | Get compressed file summary (10x smaller) |
203
+
204
+ ### Learning Tools (3)
205
+ | Tool | Description |
206
+ |------|-------------|
207
+ | `get_predicted_files` | Files predicted to be relevant |
208
+ | `get_learning_stats` | Usage statistics |
209
+ | `mark_context_useful` | Feedback for learning |
210
+
211
+ ### Multi-Project Tools (6)
212
+ | Tool | Description |
213
+ |------|-------------|
214
+ | `list_projects` | List all registered projects |
215
+ | `switch_project` | Switch active project |
216
+ | `search_all_projects` | Search across all projects |
217
+ | `discover_projects` | Find projects on system |
218
+ | `record_decision_with_author` | Decision with author attribution |
219
+ | `update_decision_status` | Update decision lifecycle |
220
+ | `export_decisions_to_adr` | Export to ADR markdown files |
221
+
222
+ ### Feature Context Tools (4)
223
+ | Tool | Description |
224
+ |------|-------------|
225
+ | `get_active_context` | Get current work session context |
226
+ | `set_feature_context` | Start tracking a feature |
227
+ | `list_recent_contexts` | List recent work sessions |
228
+ | `switch_feature_context` | Switch to previous session |
229
+
230
+ ### Living Documentation Tools (7)
231
+ | Tool | Description |
232
+ |------|-------------|
233
+ | `generate_docs` | Generate documentation |
234
+ | `get_architecture` | Get project architecture overview |
235
+ | `get_component_doc` | Get detailed component docs |
236
+ | `get_changelog` | Get changelog of recent changes |
237
+ | `validate_docs` | Check for outdated docs |
238
+ | `what_happened` | Query recent project activity |
239
+ | `find_undocumented` | Find code lacking docs |
240
+
241
+ ### Context Rot Prevention Tools (4)
242
+ | Tool | Description |
243
+ |------|-------------|
244
+ | `get_context_health` | Check context health |
245
+ | `trigger_compaction` | Manually compact context |
246
+ | `mark_critical` | Mark content as critical |
247
+ | `get_critical_context` | Get critical items |
248
+
249
+ ### Confidence Scoring Tools (3)
250
+ | Tool | Description |
251
+ |------|-------------|
252
+ | `get_confidence` | Get confidence score for code |
253
+ | `list_sources` | List sources for a suggestion |
254
+ | `check_conflicts` | Check for decision conflicts |
255
+
256
+ ### Change Intelligence Tools (4)
257
+ | Tool | Description |
258
+ |------|-------------|
259
+ | `what_changed` | Query what changed |
260
+ | `why_broke` | Diagnose why something broke |
261
+ | `find_similar_bugs` | Find similar bugs from history |
262
+ | `suggest_fix` | Get fix suggestions |
263
+
264
+ ### Architecture Enforcement Tools (7)
265
+ | Tool | Description |
266
+ |------|-------------|
267
+ | `validate_pattern` | Validate code against patterns |
268
+ | `suggest_existing` | Find existing functions |
269
+ | `learn_pattern` | Teach a new pattern |
270
+ | `list_patterns` | List all patterns |
271
+ | `get_pattern` | Get pattern details |
272
+ | `add_pattern_example` | Add example to pattern |
273
+ | `get_architecture_stats` | Get architecture statistics |
274
+
275
+ ### Test Awareness Tools (4)
276
+ | Tool | Description |
277
+ |------|-------------|
278
+ | `get_related_tests` | Get tests for a file/function |
279
+ | `check_tests` | Check if change breaks tests |
280
+ | `suggest_test_update` | Get test update suggestions |
281
+ | `get_test_coverage` | Get test coverage |
282
+
283
+ ---
284
+
285
+ ## Troubleshooting
286
+
287
+ ### "MCP server failed" or won't connect
288
+
289
+ **Most common cause:** Relative paths don't work reliably.
290
+
291
+ ```json
292
+ // ❌ WRONG - Relative path
293
+ "command": ["node", "dist/index.js", "--project", "."]
294
+
295
+ // ✅ CORRECT - Absolute path
296
+ "command": ["node", "C:\\Users\\you\\memorylayer\\dist\\index.js", "--project", "."]
297
+ ```
298
+
299
+ ### "Configuration is invalid"
300
+
301
+ Ensure `command` is an array of strings:
302
+
303
+ ```json
304
+ // ❌ WRONG - Single string
305
+ "command": "node dist/index.js --project ."
306
+
307
+ // ✅ CORRECT - Array of strings
308
+ "command": ["node", "dist/index.js", "--project", "."]
309
+ ```
310
+
311
+ ### Server starts but immediately fails
312
+
313
+ **Check if MemoryLayer runs manually first:**
314
+
315
+ ```bash
316
+ node C:\path\to\memorylayer\dist\index.js --project C:\path\to\your\project
317
+ ```
318
+
319
+ If you see errors, the issue is with MemoryLayer itself, not OpenCode.
320
+
321
+ **Common errors:**
322
+ - "Cannot find module" - Run `npm run build` first
323
+ - "ENOENT" - Path is wrong
324
+ - Database errors - Delete `~/.memorylayer/projects/` and retry
325
+
326
+ ### "No tools available" after connecting
327
+
328
+ 1. Verify connection with `/mcp` inside OpenCode
329
+ 2. Ensure `enabled: true` is set in config
330
+ 3. Restart OpenCode after config changes
331
+
332
+ ### Check Server Startup Manually
333
+
334
+ Test if MemoryLayer starts correctly:
335
+
336
+ ```bash
337
+ # Windows
338
+ node C:\path\to\memorylayer\dist\index.js --project C:\path\to\project
339
+
340
+ # macOS/Linux
341
+ node /path/to/memorylayer/dist/index.js --project /path/to/project
342
+ ```
343
+
344
+ You should see:
345
+ ```
346
+ MemoryLayer starting...
347
+ Project: /path/to/project
348
+ Indexing started...
349
+ Indexing complete: XX files indexed
350
+ MemoryLayer MCP server started
351
+ ```
352
+
353
+ ### View Debug Logs
354
+
355
+ Run OpenCode with debug logging:
356
+
357
+ ```bash
358
+ opencode --log-level DEBUG
359
+ ```
360
+
361
+ ### Reset MemoryLayer Data
362
+
363
+ If you have persistent issues, clear the data:
364
+
365
+ ```bash
366
+ # Windows
367
+ rmdir /s %USERPROFILE%\.memorylayer
368
+
369
+ # macOS/Linux
370
+ rm -rf ~/.memorylayer
371
+ ```
372
+
373
+ ---
374
+
375
+ ## Example Usage in OpenCode
376
+
377
+ Once configured, try these prompts:
378
+
379
+ ```
380
+ > Search for authentication code in this project
381
+
382
+ > What architectural decisions have been made?
383
+
384
+ > Show me the project summary
385
+
386
+ > Find the function that handles user login
387
+
388
+ > What changed yesterday?
389
+
390
+ > Why did the tests break?
391
+
392
+ > Check if this code follows our patterns: async function fetchData() { ... }
393
+
394
+ > Get tests related to src/auth/login.ts
395
+
396
+ > Record a decision: We chose SQLite because it requires no server setup
397
+ ```
398
+
399
+ ---
400
+
401
+ ## Data Storage
402
+
403
+ MemoryLayer stores data in:
404
+
405
+ ```
406
+ ~/.memorylayer/
407
+ ├── registry.json # Project registry
408
+ └── projects/
409
+ └── {project-name}-{hash}/
410
+ ├── memorylayer.db # SQLite database
411
+ └── tier1.json # Working context
412
+ ```
413
+
414
+ ---
415
+
416
+ ## Links
417
+
418
+ - [OpenCode Documentation](https://opencode.ai/docs/)
419
+ - [MCP Protocol](https://modelcontextprotocol.io/)
420
+ - [MemoryLayer API Reference](./API.md)
421
+ - [MemoryLayer Architecture](./ARCHITECTURE.md)
422
+
423
+ ---
424
+
425
+ *Last updated: February 2026*
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "neuronlayer",
3
- "version": "0.2.7",
3
+ "version": "0.2.8",
4
4
  "description": "MCP server that gives AI assistants persistent understanding of your codebase",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -9,7 +9,8 @@
9
9
  },
10
10
  "files": [
11
11
  "dist/**",
12
- "wasm/**"
12
+ "wasm/**",
13
+ "doc/**"
13
14
  ],
14
15
  "scripts": {
15
16
  "build": "node esbuild.config.js",