@grec0/memory-bank-mcp 0.1.6 → 0.1.7
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 +442 -442
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,131 +1,131 @@
|
|
|
1
1
|
# Memory Bank MCP - Semantic Code Indexing
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
## 🧠
|
|
6
|
-
|
|
7
|
-
**Memory Bank**
|
|
8
|
-
|
|
9
|
-
- **
|
|
10
|
-
- **
|
|
11
|
-
- **
|
|
12
|
-
- **
|
|
13
|
-
- **
|
|
14
|
-
- **Multi-
|
|
15
|
-
|
|
16
|
-
###
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
- ❌
|
|
20
|
-
- ❌
|
|
21
|
-
- ❌
|
|
22
|
-
- ❌
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
- ✅
|
|
26
|
-
- ✅
|
|
27
|
-
- ✅
|
|
28
|
-
- ✅
|
|
29
|
-
- ✅ **
|
|
30
|
-
|
|
31
|
-
## 🚀
|
|
32
|
-
|
|
33
|
-
### Core Memory Bank (
|
|
34
|
-
- **🔍
|
|
35
|
-
- **🧩 Chunking
|
|
36
|
-
- **⚡
|
|
37
|
-
- **💾 Cache
|
|
38
|
-
- **🎯
|
|
39
|
-
- **📊
|
|
40
|
-
- **🔒
|
|
41
|
-
- **🔀 Multi-
|
|
42
|
-
|
|
43
|
-
### Project Knowledge Layer (
|
|
44
|
-
- **📄
|
|
45
|
-
- **🧠
|
|
46
|
-
- **🔄
|
|
47
|
-
- **📚
|
|
48
|
-
|
|
49
|
-
### Context Management (
|
|
50
|
-
- **🚀
|
|
51
|
-
- **📝 Tracking
|
|
52
|
-
- **📋 Log
|
|
53
|
-
- **📊
|
|
54
|
-
- **📡 MCP Resources**:
|
|
55
|
-
|
|
56
|
-
## 📋
|
|
3
|
+
MCP (Model Context Protocol) server for semantic code indexing. Enables AI agents like Claude, Copilot, Cursor, and others to maintain a "persistent memory" of entire codebases through vector embeddings and semantic search.
|
|
4
|
+
|
|
5
|
+
## 🧠 What is Memory Bank?
|
|
6
|
+
|
|
7
|
+
**Memory Bank** is an external memory system for code agents that solves the fundamental problem of context loss in AIs. It works as the project's "external brain":
|
|
8
|
+
|
|
9
|
+
- **Indexes** all your code using OpenAI embeddings
|
|
10
|
+
- **Chunks** intelligently using AST parsing (functions, classes, methods)
|
|
11
|
+
- **Stores** vectors in LanceDB for ultra-fast searches
|
|
12
|
+
- **Searches** semantically: ask in natural language, get relevant code
|
|
13
|
+
- **Updates** incrementally: only reindexes modified files
|
|
14
|
+
- **Multi-project**: query code from any indexed project from any workspace
|
|
15
|
+
|
|
16
|
+
### Why do you need it?
|
|
17
|
+
|
|
18
|
+
Without Memory Bank, AIs:
|
|
19
|
+
- ❌ Forget everything between sessions
|
|
20
|
+
- ❌ Only see small code snippets
|
|
21
|
+
- ❌ Hallucinate non-existent implementations
|
|
22
|
+
- ❌ Give generic answers without context
|
|
23
|
+
|
|
24
|
+
With Memory Bank, AIs:
|
|
25
|
+
- ✅ Remember the entire codebase
|
|
26
|
+
- ✅ Understand architecture and patterns
|
|
27
|
+
- ✅ Respond with real project code
|
|
28
|
+
- ✅ Generate code consistent with your style
|
|
29
|
+
- ✅ **Query multiple indexed projects** simultaneously
|
|
30
|
+
|
|
31
|
+
## 🚀 Features
|
|
32
|
+
|
|
33
|
+
### Core Memory Bank (Precise Search)
|
|
34
|
+
- **🔍 Semantic Search**: Ask "how does authentication work?" and get relevant code
|
|
35
|
+
- **🧩 Intelligent Chunking**: AST parsing for TS/JS/Python with token limits (8192 max)
|
|
36
|
+
- **⚡ Incremental Updates**: Only reindexes modified files (hash-based detection)
|
|
37
|
+
- **💾 Embedding Cache**: Avoids regenerating embeddings unnecessarily
|
|
38
|
+
- **🎯 Advanced Filters**: By file, language, chunk type
|
|
39
|
+
- **📊 Detailed Statistics**: Know the state of your index at all times
|
|
40
|
+
- **🔒 Privacy**: Local vector store, respects .gitignore and .memoryignore
|
|
41
|
+
- **🔀 Multi-Project**: Query any indexed project using its `projectId`
|
|
42
|
+
|
|
43
|
+
### Project Knowledge Layer (Global Knowledge)
|
|
44
|
+
- **📄 Automatic Documentation**: Generates 6 structured markdown documents about the project
|
|
45
|
+
- **🧠 AI with Reasoning**: Uses OpenAI Responses API with reasoning models (gpt-5-mini)
|
|
46
|
+
- **🔄 Smart Updates**: Only regenerates documents affected by changes
|
|
47
|
+
- **📚 Global Context**: Complements precise search with high-level vision
|
|
48
|
+
|
|
49
|
+
### Context Management (Session Management) 🆕
|
|
50
|
+
- **🚀 Quick Initialization**: Creates Memory Bank structure with initial templates (no AI)
|
|
51
|
+
- **📝 Session Tracking**: Records active context, recent changes, and next steps
|
|
52
|
+
- **📋 Decision Log**: Documents technical decisions with rationale and alternatives
|
|
53
|
+
- **📊 Progress Tracking**: Manages tasks, milestones, and blockers
|
|
54
|
+
- **📡 MCP Resources**: Direct read-only access to documents via URIs
|
|
55
|
+
|
|
56
|
+
## 📋 Requirements
|
|
57
57
|
|
|
58
58
|
- **Node.js** >= 18.0.0
|
|
59
|
-
- **OpenAI API Key**: [
|
|
60
|
-
- **
|
|
59
|
+
- **OpenAI API Key**: [Get one here](https://platform.openai.com/api-keys)
|
|
60
|
+
- **Disk space**: ~10MB per 10,000 files (embeddings + metadata)
|
|
61
61
|
|
|
62
|
-
## 🛠️
|
|
62
|
+
## 🛠️ Installation
|
|
63
63
|
|
|
64
|
-
###
|
|
64
|
+
### Option 1: NPX (Recommended)
|
|
65
65
|
|
|
66
|
-
|
|
66
|
+
The easiest way to use Memory Bank MCP without local installation:
|
|
67
67
|
|
|
68
68
|
```bash
|
|
69
69
|
npx @grec0/memory-bank-mcp@latest
|
|
70
70
|
```
|
|
71
71
|
|
|
72
|
-
###
|
|
72
|
+
### Option 2: Local Installation
|
|
73
73
|
|
|
74
|
-
|
|
74
|
+
For development or contribution:
|
|
75
75
|
|
|
76
76
|
```bash
|
|
77
|
-
#
|
|
77
|
+
# Clone repository
|
|
78
78
|
git clone https://github.com/gcorroto/memory-bank-mcp.git
|
|
79
79
|
cd memory-bank-mcp
|
|
80
80
|
|
|
81
|
-
#
|
|
81
|
+
# Install dependencies
|
|
82
82
|
npm install
|
|
83
83
|
|
|
84
|
-
#
|
|
84
|
+
# Build
|
|
85
85
|
npm run build
|
|
86
86
|
|
|
87
|
-
#
|
|
87
|
+
# Run
|
|
88
88
|
npm run start
|
|
89
89
|
```
|
|
90
90
|
|
|
91
|
-
## ⚙️
|
|
91
|
+
## ⚙️ Complete Configuration
|
|
92
92
|
|
|
93
|
-
### Variables
|
|
93
|
+
### Environment Variables
|
|
94
94
|
|
|
95
|
-
Memory Bank
|
|
95
|
+
Memory Bank is configured through environment variables. You can set them in your MCP client or in a `.env` file:
|
|
96
96
|
|
|
97
|
-
#### Variables
|
|
97
|
+
#### Required Variables
|
|
98
98
|
|
|
99
|
-
| Variable |
|
|
99
|
+
| Variable | Description |
|
|
100
100
|
|----------|-------------|
|
|
101
|
-
| `OPENAI_API_KEY` | **
|
|
101
|
+
| `OPENAI_API_KEY` | **REQUIRED**. Your OpenAI API key |
|
|
102
102
|
|
|
103
|
-
#### Variables
|
|
103
|
+
#### Indexing Variables
|
|
104
104
|
|
|
105
|
-
| Variable | Default |
|
|
105
|
+
| Variable | Default | Description |
|
|
106
106
|
|----------|---------|-------------|
|
|
107
|
-
| `MEMORYBANK_STORAGE_PATH` | `.memorybank` |
|
|
108
|
-
| `MEMORYBANK_WORKSPACE_ROOT` | `process.cwd()` |
|
|
109
|
-
| `MEMORYBANK_EMBEDDING_MODEL` | `text-embedding-3-small` |
|
|
110
|
-
| `MEMORYBANK_EMBEDDING_DIMENSIONS` | `1536` |
|
|
111
|
-
| `MEMORYBANK_MAX_TOKENS` | `7500` |
|
|
112
|
-
| `MEMORYBANK_CHUNK_OVERLAP_TOKENS` | `200` |
|
|
107
|
+
| `MEMORYBANK_STORAGE_PATH` | `.memorybank` | Directory where the vector index is stored |
|
|
108
|
+
| `MEMORYBANK_WORKSPACE_ROOT` | `process.cwd()` | Workspace root (usually auto-detected) |
|
|
109
|
+
| `MEMORYBANK_EMBEDDING_MODEL` | `text-embedding-3-small` | OpenAI embedding model |
|
|
110
|
+
| `MEMORYBANK_EMBEDDING_DIMENSIONS` | `1536` | Vector dimensions (1536 or 512) |
|
|
111
|
+
| `MEMORYBANK_MAX_TOKENS` | `7500` | Maximum tokens per chunk (limit: 8192) |
|
|
112
|
+
| `MEMORYBANK_CHUNK_OVERLAP_TOKENS` | `200` | Overlap between chunks to maintain context |
|
|
113
113
|
|
|
114
|
-
####
|
|
114
|
+
#### Project Knowledge Layer Variables
|
|
115
115
|
|
|
116
|
-
| Variable | Default |
|
|
116
|
+
| Variable | Default | Description |
|
|
117
117
|
|----------|---------|-------------|
|
|
118
|
-
| `MEMORYBANK_REASONING_MODEL` | `gpt-5-mini` |
|
|
119
|
-
| `MEMORYBANK_REASONING_EFFORT` | `medium` |
|
|
120
|
-
| `MEMORYBANK_AUTO_UPDATE_DOCS` | `false` | Auto-
|
|
118
|
+
| `MEMORYBANK_REASONING_MODEL` | `gpt-5-mini` | Model for generating documentation (supports reasoning) |
|
|
119
|
+
| `MEMORYBANK_REASONING_EFFORT` | `medium` | Reasoning level: `low`, `medium`, `high` |
|
|
120
|
+
| `MEMORYBANK_AUTO_UPDATE_DOCS` | `false` | Auto-regenerate docs when indexing code |
|
|
121
121
|
|
|
122
|
-
###
|
|
122
|
+
### Configuration in Cursor IDE
|
|
123
123
|
|
|
124
|
-
|
|
124
|
+
Edit your MCP configuration file:
|
|
125
125
|
|
|
126
126
|
**Windows**: `%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
|
|
127
127
|
|
|
128
|
-
####
|
|
128
|
+
#### Minimal Configuration
|
|
129
129
|
|
|
130
130
|
```json
|
|
131
131
|
{
|
|
@@ -142,7 +142,7 @@ Edita tu archivo de configuración de MCP:
|
|
|
142
142
|
}
|
|
143
143
|
```
|
|
144
144
|
|
|
145
|
-
####
|
|
145
|
+
#### Complete Configuration (Recommended)
|
|
146
146
|
|
|
147
147
|
```json
|
|
148
148
|
{
|
|
@@ -166,7 +166,7 @@ Edita tu archivo de configuración de MCP:
|
|
|
166
166
|
}
|
|
167
167
|
```
|
|
168
168
|
|
|
169
|
-
###
|
|
169
|
+
### Configuration in Claude Desktop
|
|
170
170
|
|
|
171
171
|
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
172
172
|
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
@@ -188,15 +188,15 @@ Edita tu archivo de configuración de MCP:
|
|
|
188
188
|
}
|
|
189
189
|
```
|
|
190
190
|
|
|
191
|
-
###
|
|
191
|
+
### Configuration with Local Installation
|
|
192
192
|
|
|
193
193
|
```json
|
|
194
194
|
{
|
|
195
195
|
"mcpServers": {
|
|
196
196
|
"memory-bank": {
|
|
197
197
|
"command": "node",
|
|
198
|
-
"args": ["/
|
|
199
|
-
"cwd": "/
|
|
198
|
+
"args": ["/absolute/path/memory-bank-mcp/dist/index.js"],
|
|
199
|
+
"cwd": "/absolute/path/memory-bank-mcp",
|
|
200
200
|
"env": {
|
|
201
201
|
"OPENAI_API_KEY": "sk-your-api-key-here"
|
|
202
202
|
}
|
|
@@ -207,35 +207,35 @@ Edita tu archivo de configuración de MCP:
|
|
|
207
207
|
|
|
208
208
|
---
|
|
209
209
|
|
|
210
|
-
## 📄
|
|
210
|
+
## 📄 Project Documentation System (Project Knowledge Layer)
|
|
211
211
|
|
|
212
|
-
Memory Bank
|
|
212
|
+
Memory Bank includes an intelligent documentation system that generates and maintains structured knowledge about your project using AI with reasoning capabilities.
|
|
213
213
|
|
|
214
|
-
###
|
|
214
|
+
### How Does It Work?
|
|
215
215
|
|
|
216
|
-
1. **
|
|
217
|
-
2. **
|
|
218
|
-
3. **
|
|
219
|
-
4. **
|
|
216
|
+
1. **Code Analysis**: The system analyzes indexed code using semantic search
|
|
217
|
+
2. **AI Generation**: Uses reasoning models (gpt-5-mini) to generate structured documentation
|
|
218
|
+
3. **Incremental Updates**: Only regenerates documents affected by significant changes
|
|
219
|
+
4. **Persistent Storage**: Documents are saved in `.memorybank/projects/{projectId}/docs/`
|
|
220
220
|
|
|
221
|
-
###
|
|
221
|
+
### Generated Documents
|
|
222
222
|
|
|
223
|
-
|
|
223
|
+
The system generates **6 markdown documents** that provide different perspectives of the project:
|
|
224
224
|
|
|
225
|
-
|
|
|
226
|
-
|
|
227
|
-
| `projectBrief.md` | **
|
|
228
|
-
| `productContext.md` | **
|
|
229
|
-
| `systemPatterns.md` | **
|
|
230
|
-
| `techContext.md` | **Stack
|
|
231
|
-
| `activeContext.md` | **
|
|
232
|
-
| `progress.md` | **
|
|
225
|
+
| Document | Purpose | Content |
|
|
226
|
+
|----------|---------|---------|
|
|
227
|
+
| `projectBrief.md` | **General Description** | What the project is, its main purpose, key features |
|
|
228
|
+
| `productContext.md` | **Business Perspective** | Why it exists, problems it solves, target users, UX |
|
|
229
|
+
| `systemPatterns.md` | **Architecture and Patterns** | Code structure, design patterns, technical decisions |
|
|
230
|
+
| `techContext.md` | **Tech Stack** | Technologies, dependencies, configurations, integrations |
|
|
231
|
+
| `activeContext.md` | **Current State** | What's being worked on, recent changes, next steps |
|
|
232
|
+
| `progress.md` | **Tracking** | Change history, what works, what's missing, known issues |
|
|
233
233
|
|
|
234
|
-
###
|
|
234
|
+
### Documentation Tools
|
|
235
235
|
|
|
236
236
|
#### `memorybank_generate_project_docs`
|
|
237
237
|
|
|
238
|
-
|
|
238
|
+
Generates or regenerates project documentation.
|
|
239
239
|
|
|
240
240
|
```json
|
|
241
241
|
{
|
|
@@ -244,27 +244,27 @@ Genera o regenera la documentación del proyecto.
|
|
|
244
244
|
}
|
|
245
245
|
```
|
|
246
246
|
|
|
247
|
-
- `projectId` **(
|
|
248
|
-
- `force` (
|
|
247
|
+
- `projectId` **(REQUIRED)**: Project ID
|
|
248
|
+
- `force` (optional): `true` to regenerate everything, `false` for incremental updates
|
|
249
249
|
|
|
250
250
|
#### `memorybank_get_project_docs`
|
|
251
251
|
|
|
252
|
-
|
|
252
|
+
Reads generated documentation.
|
|
253
253
|
|
|
254
254
|
```json
|
|
255
|
-
//
|
|
255
|
+
// Get summary of all documents
|
|
256
256
|
{
|
|
257
257
|
"projectId": "my-project",
|
|
258
258
|
"document": "summary"
|
|
259
259
|
}
|
|
260
260
|
|
|
261
|
-
//
|
|
261
|
+
// Get specific document
|
|
262
262
|
{
|
|
263
263
|
"projectId": "my-project",
|
|
264
264
|
"document": "systemPatterns"
|
|
265
265
|
}
|
|
266
266
|
|
|
267
|
-
//
|
|
267
|
+
// Get all complete documents
|
|
268
268
|
{
|
|
269
269
|
"projectId": "my-project",
|
|
270
270
|
"document": "all",
|
|
@@ -272,99 +272,99 @@ Lee la documentación generada.
|
|
|
272
272
|
}
|
|
273
273
|
```
|
|
274
274
|
|
|
275
|
-
###
|
|
275
|
+
### Documentation Workflow
|
|
276
276
|
|
|
277
277
|
```
|
|
278
|
-
1.
|
|
278
|
+
1. Index code
|
|
279
279
|
memorybank_index_code({ projectId: "my-project" })
|
|
280
280
|
|
|
281
|
-
2.
|
|
281
|
+
2. Generate documentation
|
|
282
282
|
memorybank_generate_project_docs({ projectId: "my-project" })
|
|
283
283
|
|
|
284
|
-
3.
|
|
284
|
+
3. Query documentation at the start of each session
|
|
285
285
|
memorybank_get_project_docs({ projectId: "my-project", document: "activeContext" })
|
|
286
286
|
|
|
287
|
-
4.
|
|
287
|
+
4. Search specific code
|
|
288
288
|
memorybank_search({ projectId: "my-project", query: "..." })
|
|
289
289
|
```
|
|
290
290
|
|
|
291
|
-
### Auto-
|
|
291
|
+
### Auto-Update Documentation
|
|
292
292
|
|
|
293
|
-
|
|
293
|
+
If you configure `MEMORYBANK_AUTO_UPDATE_DOCS=true`, documents will be automatically regenerated after each indexing. This is useful for keeping documentation always up to date but consumes more API tokens.
|
|
294
294
|
|
|
295
295
|
---
|
|
296
296
|
|
|
297
|
-
## 🔀 Multi-
|
|
297
|
+
## 🔀 Multi-Project: Cross-Project Queries
|
|
298
298
|
|
|
299
|
-
|
|
299
|
+
A powerful feature of Memory Bank is the ability to **query any indexed project from any workspace**.
|
|
300
300
|
|
|
301
|
-
###
|
|
301
|
+
### How Does It Work?
|
|
302
302
|
|
|
303
|
-
|
|
303
|
+
All indexed projects are stored in a shared vector store, identified by their `projectId`. This means:
|
|
304
304
|
|
|
305
|
-
1. **
|
|
306
|
-
2. **
|
|
307
|
-
3. **
|
|
305
|
+
1. **You can work on Project A** and query code from Project B
|
|
306
|
+
2. **Agents can learn** from similar already-indexed projects
|
|
307
|
+
3. **Reuse patterns** from other projects in your organization
|
|
308
308
|
|
|
309
|
-
###
|
|
309
|
+
### Usage Example
|
|
310
310
|
|
|
311
311
|
```
|
|
312
|
-
#
|
|
312
|
+
# You're working on "frontend-app" but need to see how something was done in "backend-api"
|
|
313
313
|
|
|
314
|
-
|
|
314
|
+
User: How was authentication implemented in the backend-api project?
|
|
315
315
|
|
|
316
|
-
|
|
317
|
-
projectId: "backend-api", //
|
|
318
|
-
query: "
|
|
316
|
+
Agent: [executes memorybank_search({
|
|
317
|
+
projectId: "backend-api", // Another project
|
|
318
|
+
query: "JWT middleware authentication"
|
|
319
319
|
})]
|
|
320
320
|
|
|
321
|
-
|
|
322
|
-
-
|
|
323
|
-
-
|
|
324
|
-
-
|
|
321
|
+
Found the implementation in backend-api:
|
|
322
|
+
- The auth middleware is in src/middleware/auth.ts
|
|
323
|
+
- Uses JWT with refresh tokens
|
|
324
|
+
- Validation is done with jsonwebtoken...
|
|
325
325
|
```
|
|
326
326
|
|
|
327
|
-
###
|
|
327
|
+
### Requirements for Multi-Project
|
|
328
328
|
|
|
329
|
-
1. **
|
|
330
|
-
2. **
|
|
331
|
-
3. **
|
|
329
|
+
1. **The project must be previously indexed** with its `projectId`
|
|
330
|
+
2. **Use the correct projectId** when making queries
|
|
331
|
+
3. **Documentation is independent** per project
|
|
332
332
|
|
|
333
|
-
###
|
|
333
|
+
### Real Example: Two Related Projects
|
|
334
334
|
|
|
335
335
|
```json
|
|
336
|
-
//
|
|
336
|
+
// Project 1: a2a_gateway (already indexed)
|
|
337
337
|
memorybank_search({
|
|
338
338
|
"projectId": "a2a_gateway",
|
|
339
|
-
"query": "
|
|
339
|
+
"query": "how agents are registered"
|
|
340
340
|
})
|
|
341
341
|
|
|
342
|
-
//
|
|
342
|
+
// Project 2: GREC0AI (current workspace)
|
|
343
343
|
memorybank_search({
|
|
344
344
|
"projectId": "GREC0AI",
|
|
345
|
-
"query": "
|
|
345
|
+
"query": "AgentEntity implementation"
|
|
346
346
|
})
|
|
347
347
|
|
|
348
|
-
//
|
|
348
|
+
// You can query both in the same session!
|
|
349
349
|
```
|
|
350
350
|
|
|
351
351
|
---
|
|
352
352
|
|
|
353
|
-
## 📚
|
|
353
|
+
## 📚 Available Tools
|
|
354
354
|
|
|
355
|
-
> **⚠️
|
|
355
|
+
> **⚠️ IMPORTANT**: All tools require mandatory `projectId`. This ID must match the one defined in your `AGENTS.md` file.
|
|
356
356
|
|
|
357
357
|
### `memorybank_index_code`
|
|
358
358
|
|
|
359
|
-
|
|
359
|
+
Indexes code semantically to enable searches.
|
|
360
360
|
|
|
361
|
-
**
|
|
362
|
-
- `projectId` **(
|
|
363
|
-
- `path` (
|
|
364
|
-
- `recursive` (
|
|
365
|
-
- `forceReindex` (
|
|
361
|
+
**Parameters:**
|
|
362
|
+
- `projectId` **(REQUIRED)**: Unique project identifier
|
|
363
|
+
- `path` (optional): Relative or absolute path (default: workspace root)
|
|
364
|
+
- `recursive` (optional): Index subdirectories (default: true)
|
|
365
|
+
- `forceReindex` (optional): Force complete reindexing (default: false)
|
|
366
366
|
|
|
367
|
-
**
|
|
367
|
+
**Example:**
|
|
368
368
|
```json
|
|
369
369
|
{
|
|
370
370
|
"projectId": "my-project",
|
|
@@ -375,21 +375,21 @@ Indexa código semánticamente para permitir búsquedas.
|
|
|
375
375
|
|
|
376
376
|
### `memorybank_search`
|
|
377
377
|
|
|
378
|
-
|
|
378
|
+
Searches code by semantic similarity.
|
|
379
379
|
|
|
380
|
-
**
|
|
381
|
-
- `projectId` **(
|
|
382
|
-
- `query` (
|
|
383
|
-
- `topK` (
|
|
384
|
-
- `minScore` (
|
|
385
|
-
- `filterByFile` (
|
|
386
|
-
- `filterByLanguage` (
|
|
380
|
+
**Parameters:**
|
|
381
|
+
- `projectId` **(REQUIRED)**: Project identifier to search in
|
|
382
|
+
- `query` (required): Natural language query
|
|
383
|
+
- `topK` (optional): Number of results (default: 10)
|
|
384
|
+
- `minScore` (optional): Minimum score 0-1 (default: 0.4)
|
|
385
|
+
- `filterByFile` (optional): Filter by file pattern
|
|
386
|
+
- `filterByLanguage` (optional): Filter by language
|
|
387
387
|
|
|
388
|
-
**
|
|
388
|
+
**Example:**
|
|
389
389
|
```json
|
|
390
390
|
{
|
|
391
391
|
"projectId": "my-project",
|
|
392
|
-
"query": "
|
|
392
|
+
"query": "function that authenticates users with JWT",
|
|
393
393
|
"topK": 5,
|
|
394
394
|
"minScore": 0.8
|
|
395
395
|
}
|
|
@@ -397,36 +397,36 @@ Busca código por similitud semántica.
|
|
|
397
397
|
|
|
398
398
|
### `memorybank_read_file`
|
|
399
399
|
|
|
400
|
-
|
|
400
|
+
Reads file contents.
|
|
401
401
|
|
|
402
|
-
**
|
|
403
|
-
- `path` (
|
|
404
|
-
- `startLine` (
|
|
405
|
-
- `endLine` (
|
|
402
|
+
**Parameters:**
|
|
403
|
+
- `path` (required): File path
|
|
404
|
+
- `startLine` (optional): Start line
|
|
405
|
+
- `endLine` (optional): End line
|
|
406
406
|
|
|
407
407
|
### `memorybank_write_file`
|
|
408
408
|
|
|
409
|
-
|
|
409
|
+
Writes a file and automatically reindexes it.
|
|
410
410
|
|
|
411
|
-
**
|
|
412
|
-
- `projectId` **(
|
|
413
|
-
- `path` (
|
|
414
|
-
- `content` (
|
|
415
|
-
- `autoReindex` (
|
|
411
|
+
**Parameters:**
|
|
412
|
+
- `projectId` **(REQUIRED)**: Project identifier for reindexing
|
|
413
|
+
- `path` (required): File path
|
|
414
|
+
- `content` (required): File content
|
|
415
|
+
- `autoReindex` (optional): Auto-reindex (default: true)
|
|
416
416
|
|
|
417
417
|
### `memorybank_get_stats`
|
|
418
418
|
|
|
419
|
-
|
|
419
|
+
Gets Memory Bank statistics.
|
|
420
420
|
|
|
421
421
|
### `memorybank_analyze_coverage`
|
|
422
422
|
|
|
423
|
-
|
|
423
|
+
Analyzes project indexing coverage.
|
|
424
424
|
|
|
425
|
-
**
|
|
426
|
-
- `projectId` **(
|
|
427
|
-
- `path` **(
|
|
425
|
+
**Parameters:**
|
|
426
|
+
- `projectId` **(REQUIRED)**: Project identifier to analyze
|
|
427
|
+
- `path` **(REQUIRED)**: Absolute workspace path to analyze
|
|
428
428
|
|
|
429
|
-
**
|
|
429
|
+
**Example:**
|
|
430
430
|
```json
|
|
431
431
|
{
|
|
432
432
|
"projectId": "my-project",
|
|
@@ -436,38 +436,38 @@ Analiza la cobertura de indexación del proyecto.
|
|
|
436
436
|
|
|
437
437
|
### `memorybank_generate_project_docs`
|
|
438
438
|
|
|
439
|
-
|
|
439
|
+
Generates structured project documentation using AI with reasoning.
|
|
440
440
|
|
|
441
|
-
**
|
|
442
|
-
- `projectId` **(
|
|
443
|
-
- `force` (
|
|
441
|
+
**Parameters:**
|
|
442
|
+
- `projectId` **(REQUIRED)**: Project identifier
|
|
443
|
+
- `force` (optional): Force regeneration (default: false)
|
|
444
444
|
|
|
445
445
|
### `memorybank_get_project_docs`
|
|
446
446
|
|
|
447
|
-
|
|
447
|
+
Reads AI-generated project documentation.
|
|
448
448
|
|
|
449
|
-
**
|
|
450
|
-
- `projectId` **(
|
|
451
|
-
- `document` (
|
|
452
|
-
- `format` (
|
|
449
|
+
**Parameters:**
|
|
450
|
+
- `projectId` **(REQUIRED)**: Project identifier
|
|
451
|
+
- `document` (optional): `"summary"`, `"all"`, or specific name (`projectBrief`, `systemPatterns`, etc.)
|
|
452
|
+
- `format` (optional): `"full"` or `"summary"` (default: "full")
|
|
453
453
|
|
|
454
454
|
---
|
|
455
455
|
|
|
456
|
-
## 🔄
|
|
456
|
+
## 🔄 Context Management Tools (Cline-style)
|
|
457
457
|
|
|
458
|
-
|
|
458
|
+
These tools allow managing project context manually, complementing automatic AI generation.
|
|
459
459
|
|
|
460
460
|
### `memorybank_initialize`
|
|
461
461
|
|
|
462
|
-
|
|
462
|
+
Initializes Memory Bank for a new project. Creates directory structure and 7 markdown documents with initial templates. **Does not use AI**.
|
|
463
463
|
|
|
464
|
-
**
|
|
465
|
-
- `projectId` **(
|
|
466
|
-
- `projectPath` **(
|
|
467
|
-
- `projectName` (
|
|
468
|
-
- `description` (
|
|
464
|
+
**Parameters:**
|
|
465
|
+
- `projectId` **(REQUIRED)**: Unique project identifier
|
|
466
|
+
- `projectPath` **(REQUIRED)**: Absolute project path
|
|
467
|
+
- `projectName` (optional): Human-readable project name
|
|
468
|
+
- `description` (optional): Initial project description
|
|
469
469
|
|
|
470
|
-
**
|
|
470
|
+
**Example:**
|
|
471
471
|
```json
|
|
472
472
|
{
|
|
473
473
|
"projectId": "my-project",
|
|
@@ -477,28 +477,28 @@ Inicializa el Memory Bank para un proyecto nuevo. Crea la estructura de director
|
|
|
477
477
|
}
|
|
478
478
|
```
|
|
479
479
|
|
|
480
|
-
**
|
|
481
|
-
- `projectBrief.md` -
|
|
482
|
-
- `productContext.md` -
|
|
483
|
-
- `systemPatterns.md` -
|
|
484
|
-
- `techContext.md` -
|
|
485
|
-
- `activeContext.md` -
|
|
486
|
-
- `progress.md` -
|
|
487
|
-
- `decisionLog.md` -
|
|
480
|
+
**Created documents:**
|
|
481
|
+
- `projectBrief.md` - General description
|
|
482
|
+
- `productContext.md` - Product context
|
|
483
|
+
- `systemPatterns.md` - Architecture patterns
|
|
484
|
+
- `techContext.md` - Tech stack
|
|
485
|
+
- `activeContext.md` - Session context
|
|
486
|
+
- `progress.md` - Progress tracking
|
|
487
|
+
- `decisionLog.md` - Decision log
|
|
488
488
|
|
|
489
489
|
### `memorybank_update_context`
|
|
490
490
|
|
|
491
|
-
|
|
491
|
+
Updates active context with current session information. Maintains history of the last 10 sessions. **Does not use AI**.
|
|
492
492
|
|
|
493
|
-
**
|
|
494
|
-
- `projectId` **(
|
|
495
|
-
- `currentSession` (
|
|
496
|
-
- `recentChanges` (
|
|
497
|
-
- `openQuestions` (
|
|
498
|
-
- `nextSteps` (
|
|
499
|
-
- `notes` (
|
|
493
|
+
**Parameters:**
|
|
494
|
+
- `projectId` **(REQUIRED)**: Project identifier
|
|
495
|
+
- `currentSession` (optional): Session information (date, mode, task)
|
|
496
|
+
- `recentChanges` (optional): List of recent changes
|
|
497
|
+
- `openQuestions` (optional): Pending questions
|
|
498
|
+
- `nextSteps` (optional): Planned next steps
|
|
499
|
+
- `notes` (optional): Additional notes
|
|
500
500
|
|
|
501
|
-
**
|
|
501
|
+
**Example:**
|
|
502
502
|
```json
|
|
503
503
|
{
|
|
504
504
|
"projectId": "my-project",
|
|
@@ -513,19 +513,19 @@ Actualiza el contexto activo con información de la sesión actual. Mantiene his
|
|
|
513
513
|
|
|
514
514
|
### `memorybank_record_decision`
|
|
515
515
|
|
|
516
|
-
|
|
516
|
+
Records technical decisions with rationale in the decision log. **Does not use AI**.
|
|
517
517
|
|
|
518
|
-
**
|
|
519
|
-
- `projectId` **(
|
|
520
|
-
- `decision` **(
|
|
521
|
-
- `title` **(
|
|
522
|
-
- `description` **(
|
|
523
|
-
- `rationale` **(
|
|
524
|
-
- `alternatives` (
|
|
525
|
-
- `impact` (
|
|
526
|
-
- `category` (
|
|
518
|
+
**Parameters:**
|
|
519
|
+
- `projectId` **(REQUIRED)**: Project identifier
|
|
520
|
+
- `decision` **(REQUIRED)**: Object with decision information
|
|
521
|
+
- `title` **(REQUIRED)**: Decision title
|
|
522
|
+
- `description` **(REQUIRED)**: What was decided
|
|
523
|
+
- `rationale` **(REQUIRED)**: Why this decision was made
|
|
524
|
+
- `alternatives` (optional): Considered alternatives
|
|
525
|
+
- `impact` (optional): Expected impact
|
|
526
|
+
- `category` (optional): architecture, technology, dependencies, etc.
|
|
527
527
|
|
|
528
|
-
**
|
|
528
|
+
**Example:**
|
|
529
529
|
```json
|
|
530
530
|
{
|
|
531
531
|
"projectId": "my-project",
|
|
@@ -541,21 +541,21 @@ Registra decisiones técnicas con rationale en el log de decisiones. **No usa IA
|
|
|
541
541
|
|
|
542
542
|
### `memorybank_track_progress`
|
|
543
543
|
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
**
|
|
547
|
-
- `projectId` **(
|
|
548
|
-
- `progress` (
|
|
549
|
-
- `completed`:
|
|
550
|
-
- `inProgress`:
|
|
551
|
-
- `blocked`:
|
|
552
|
-
- `upcoming`:
|
|
553
|
-
- `milestone` (
|
|
554
|
-
- `blockers` (
|
|
555
|
-
- `phase` (
|
|
556
|
-
- `phaseStatus` (
|
|
557
|
-
|
|
558
|
-
**
|
|
544
|
+
Updates progress tracking with tasks, milestones, and blockers. **Does not use AI**.
|
|
545
|
+
|
|
546
|
+
**Parameters:**
|
|
547
|
+
- `projectId` **(REQUIRED)**: Project identifier
|
|
548
|
+
- `progress` (optional): Tasks to update
|
|
549
|
+
- `completed`: Completed tasks
|
|
550
|
+
- `inProgress`: Tasks in progress
|
|
551
|
+
- `blocked`: Blocked tasks
|
|
552
|
+
- `upcoming`: Upcoming tasks
|
|
553
|
+
- `milestone` (optional): Milestone to add/update (name, status, targetDate, notes)
|
|
554
|
+
- `blockers` (optional): List of blockers with severity (low/medium/high)
|
|
555
|
+
- `phase` (optional): Current project phase
|
|
556
|
+
- `phaseStatus` (optional): Phase status
|
|
557
|
+
|
|
558
|
+
**Example:**
|
|
559
559
|
```json
|
|
560
560
|
{
|
|
561
561
|
"projectId": "my-project",
|
|
@@ -574,148 +574,148 @@ Actualiza el seguimiento de progreso con tareas, milestones y blockers. **No usa
|
|
|
574
574
|
|
|
575
575
|
---
|
|
576
576
|
|
|
577
|
-
## 📡 MCP Resources (
|
|
577
|
+
## 📡 MCP Resources (Direct Access)
|
|
578
578
|
|
|
579
|
-
Memory Bank
|
|
579
|
+
Memory Bank exposes MCP resources for direct read-only access to project documents.
|
|
580
580
|
|
|
581
|
-
| Resource URI |
|
|
582
|
-
|
|
583
|
-
| `memory://{projectId}/active` |
|
|
584
|
-
| `memory://{projectId}/progress` |
|
|
585
|
-
| `memory://{projectId}/decisions` |
|
|
586
|
-
| `memory://{projectId}/context` |
|
|
587
|
-
| `memory://{projectId}/patterns` |
|
|
588
|
-
| `memory://{projectId}/brief` |
|
|
581
|
+
| Resource URI | Content |
|
|
582
|
+
|--------------|---------|
|
|
583
|
+
| `memory://{projectId}/active` | Active session context |
|
|
584
|
+
| `memory://{projectId}/progress` | Progress tracking |
|
|
585
|
+
| `memory://{projectId}/decisions` | Technical decision log |
|
|
586
|
+
| `memory://{projectId}/context` | Project context (brief + tech) |
|
|
587
|
+
| `memory://{projectId}/patterns` | System patterns |
|
|
588
|
+
| `memory://{projectId}/brief` | Project description |
|
|
589
589
|
|
|
590
|
-
**
|
|
590
|
+
**Usage example:**
|
|
591
591
|
```
|
|
592
|
-
//
|
|
592
|
+
// Access active context for "my-project"
|
|
593
593
|
memory://my-project/active
|
|
594
594
|
|
|
595
|
-
//
|
|
595
|
+
// Access decision log
|
|
596
596
|
memory://my-project/decisions
|
|
597
597
|
```
|
|
598
598
|
|
|
599
|
-
|
|
599
|
+
Resources are read-only. To modify documents, use the corresponding tools (`memorybank_update_context`, `memorybank_record_decision`, etc.).
|
|
600
600
|
|
|
601
601
|
---
|
|
602
602
|
|
|
603
|
-
## 📋
|
|
603
|
+
## 📋 Agent Instruction Templates
|
|
604
604
|
|
|
605
|
-
Memory Bank
|
|
605
|
+
Memory Bank includes instruction templates in two formats to configure agent behavior:
|
|
606
606
|
|
|
607
|
-
- **AGENTS.md** -
|
|
608
|
-
- **VSCode/Copilot** -
|
|
607
|
+
- **AGENTS.md** - Standard [agents.md](https://agents.md/) (compatible with Claude, Cursor, multiple agents)
|
|
608
|
+
- **VSCode/Copilot** - `.github/copilot-instructions.md` format for GitHub Copilot in VS Code
|
|
609
609
|
|
|
610
|
-
###
|
|
610
|
+
### Available Modes
|
|
611
611
|
|
|
612
|
-
|
|
|
613
|
-
|
|
614
|
-
| **Basic** | `AGENTS.basic.md` |
|
|
615
|
-
| **Auto-Index** | `AGENTS.auto-index.md` |
|
|
616
|
-
| **Sandboxed** | `AGENTS.sandboxed.md` |
|
|
612
|
+
| Mode | File | Ideal Use |
|
|
613
|
+
|------|------|-----------|
|
|
614
|
+
| **Basic** | `AGENTS.basic.md` | Total control, manual indexing |
|
|
615
|
+
| **Auto-Index** | `AGENTS.auto-index.md` | Active development, automatic sync |
|
|
616
|
+
| **Sandboxed** | `AGENTS.sandboxed.md` | Environments without direct file access |
|
|
617
617
|
|
|
618
618
|
### 1. Basic Mode
|
|
619
619
|
|
|
620
|
-
**
|
|
620
|
+
**For projects where you want total control.**
|
|
621
621
|
|
|
622
|
-
- ✅
|
|
623
|
-
- ✅
|
|
624
|
-
- ✅
|
|
625
|
-
- ✅
|
|
622
|
+
- ✅ Agent ALWAYS consults Memory Bank before acting
|
|
623
|
+
- ✅ Only indexes when user explicitly requests
|
|
624
|
+
- ✅ Asks permission before modifying code
|
|
625
|
+
- ✅ Suggests reindexing after changes
|
|
626
626
|
|
|
627
|
-
**Ideal
|
|
627
|
+
**Ideal for**: Critical projects, code review, onboarding.
|
|
628
628
|
|
|
629
629
|
### 2. Auto-Index Mode
|
|
630
630
|
|
|
631
|
-
**
|
|
631
|
+
**For active development with automatic synchronization.**
|
|
632
632
|
|
|
633
|
-
- ✅
|
|
634
|
-
- ✅
|
|
635
|
-
- ✅
|
|
636
|
-
- ✅
|
|
633
|
+
- ✅ Agent consults Memory Bank automatically
|
|
634
|
+
- ✅ Reindexes EVERY file after modifying it
|
|
635
|
+
- ✅ Keeps Memory Bank always up to date
|
|
636
|
+
- ✅ Can read/write files directly
|
|
637
637
|
|
|
638
|
-
**Ideal
|
|
638
|
+
**Ideal for**: Active development, rapid iteration, teams.
|
|
639
639
|
|
|
640
640
|
### 3. Sandboxed Mode
|
|
641
641
|
|
|
642
|
-
**
|
|
642
|
+
**For environments without direct file system access.**
|
|
643
643
|
|
|
644
|
-
- ✅
|
|
645
|
-
- ✅
|
|
646
|
-
- ✅
|
|
647
|
-
- ✅ Auto-
|
|
644
|
+
- ✅ Does NOT have direct file access
|
|
645
|
+
- ✅ MUST use `memorybank_read_file` to read
|
|
646
|
+
- ✅ MUST use `memorybank_write_file` to write
|
|
647
|
+
- ✅ Auto-reindexes automatically on each write
|
|
648
648
|
|
|
649
|
-
**Ideal
|
|
649
|
+
**Ideal for**: Restricted environments, remote development, security.
|
|
650
650
|
|
|
651
|
-
###
|
|
651
|
+
### Available Templates
|
|
652
652
|
|
|
653
|
-
|
|
653
|
+
All templates are available in the GitHub repository:
|
|
654
654
|
|
|
655
|
-
####
|
|
655
|
+
#### AGENTS.md Format (Cursor, Claude, Multi-agent)
|
|
656
656
|
|
|
657
|
-
|
|
|
657
|
+
| Mode | URL |
|
|
658
658
|
|------|-----|
|
|
659
659
|
| **Basic** | [AGENTS.basic.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/AGENTS.basic.md) |
|
|
660
660
|
| **Auto-Index** | [AGENTS.auto-index.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/AGENTS.auto-index.md) |
|
|
661
661
|
| **Sandboxed** | [AGENTS.sandboxed.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/AGENTS.sandboxed.md) |
|
|
662
662
|
|
|
663
|
-
**
|
|
663
|
+
**Installation:**
|
|
664
664
|
|
|
665
665
|
```bash
|
|
666
|
-
#
|
|
666
|
+
# Download template (choose one)
|
|
667
667
|
curl -o AGENTS.md https://raw.githubusercontent.com/gcorroto/memory-bank-mcp/main/templates/AGENTS.basic.md
|
|
668
|
-
#
|
|
668
|
+
# Or
|
|
669
669
|
curl -o AGENTS.md https://raw.githubusercontent.com/gcorroto/memory-bank-mcp/main/templates/AGENTS.auto-index.md
|
|
670
|
-
#
|
|
670
|
+
# Or
|
|
671
671
|
curl -o AGENTS.md https://raw.githubusercontent.com/gcorroto/memory-bank-mcp/main/templates/AGENTS.sandboxed.md
|
|
672
672
|
|
|
673
|
-
#
|
|
674
|
-
# -
|
|
675
|
-
# -
|
|
673
|
+
# Edit placeholders:
|
|
674
|
+
# - Replace {{PROJECT_ID}} with your unique project ID
|
|
675
|
+
# - Replace {{WORKSPACE_PATH}} with the absolute workspace path
|
|
676
676
|
```
|
|
677
677
|
|
|
678
|
-
####
|
|
678
|
+
#### VS Code / GitHub Copilot Format
|
|
679
679
|
|
|
680
|
-
|
|
|
680
|
+
| Mode | URL |
|
|
681
681
|
|------|-----|
|
|
682
682
|
| **Basic** | [copilot-instructions.basic.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/vscode/copilot-instructions.basic.md) |
|
|
683
683
|
| **Auto-Index** | [copilot-instructions.auto-index.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/vscode/copilot-instructions.auto-index.md) |
|
|
684
684
|
| **Sandboxed** | [copilot-instructions.sandboxed.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/vscode/copilot-instructions.sandboxed.md) |
|
|
685
685
|
| **Instructions** | [memory-bank.instructions.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/vscode/memory-bank.instructions.md) |
|
|
686
686
|
|
|
687
|
-
**
|
|
687
|
+
**Installation:**
|
|
688
688
|
|
|
689
689
|
```bash
|
|
690
|
-
#
|
|
690
|
+
# Create .github folder if it doesn't exist
|
|
691
691
|
mkdir -p .github
|
|
692
692
|
|
|
693
|
-
#
|
|
693
|
+
# Download template (choose one)
|
|
694
694
|
curl -o .github/copilot-instructions.md https://raw.githubusercontent.com/gcorroto/memory-bank-mcp/main/templates/vscode/copilot-instructions.basic.md
|
|
695
|
-
#
|
|
695
|
+
# Or
|
|
696
696
|
curl -o .github/copilot-instructions.md https://raw.githubusercontent.com/gcorroto/memory-bank-mcp/main/templates/vscode/copilot-instructions.auto-index.md
|
|
697
|
-
#
|
|
697
|
+
# Or
|
|
698
698
|
curl -o .github/copilot-instructions.md https://raw.githubusercontent.com/gcorroto/memory-bank-mcp/main/templates/vscode/copilot-instructions.sandboxed.md
|
|
699
699
|
|
|
700
|
-
#
|
|
700
|
+
# Enable in VS Code settings.json:
|
|
701
701
|
# "github.copilot.chat.codeGeneration.useInstructionFiles": true
|
|
702
702
|
```
|
|
703
703
|
|
|
704
|
-
####
|
|
704
|
+
#### Instructions with Conditional Application (VS Code)
|
|
705
705
|
|
|
706
|
-
|
|
706
|
+
To use the `.instructions.md` file that applies only to certain files:
|
|
707
707
|
|
|
708
708
|
```bash
|
|
709
|
-
#
|
|
709
|
+
# Create instructions folder
|
|
710
710
|
mkdir -p .github/instructions
|
|
711
711
|
|
|
712
|
-
#
|
|
712
|
+
# Download base instructions
|
|
713
713
|
curl -o .github/instructions/memory-bank.instructions.md https://raw.githubusercontent.com/gcorroto/memory-bank-mcp/main/templates/vscode/memory-bank.instructions.md
|
|
714
714
|
```
|
|
715
715
|
|
|
716
|
-
|
|
716
|
+
This file includes `applyTo: "**/*"` which applies to all files, but you can modify it.
|
|
717
717
|
|
|
718
|
-
###
|
|
718
|
+
### Configured AGENTS.md Example
|
|
719
719
|
|
|
720
720
|
```markdown
|
|
721
721
|
# AGENTS.md
|
|
@@ -740,78 +740,78 @@ memorybank_get_project_docs({ projectId: "my-awesome-app", document: "activeCont
|
|
|
740
740
|
|
|
741
741
|
---
|
|
742
742
|
|
|
743
|
-
## 🎯
|
|
743
|
+
## 🎯 Use Cases
|
|
744
744
|
|
|
745
|
-
### 1.
|
|
745
|
+
### 1. First Indexing
|
|
746
746
|
|
|
747
747
|
```
|
|
748
|
-
|
|
749
|
-
Claude: [
|
|
750
|
-
|
|
751
|
-
|
|
748
|
+
User: Hi, I want you to help me with my project. The projectId is "my-app"
|
|
749
|
+
Claude: [executes memorybank_get_stats]
|
|
750
|
+
I see there's no code indexed yet.
|
|
751
|
+
Would you like me to index the project so I can help you better?
|
|
752
752
|
|
|
753
|
-
|
|
754
|
-
Claude: [
|
|
755
|
-
|
|
756
|
-
|
|
753
|
+
User: Yes
|
|
754
|
+
Claude: [executes memorybank_index_code({ projectId: "my-app" })]
|
|
755
|
+
I've indexed 145 files (1,234 chunks) in 45 seconds.
|
|
756
|
+
How can I help you?
|
|
757
757
|
```
|
|
758
758
|
|
|
759
|
-
### 2.
|
|
759
|
+
### 2. Code Search
|
|
760
760
|
|
|
761
761
|
```
|
|
762
|
-
|
|
763
|
-
Claude: [
|
|
762
|
+
User: How does authentication work in this project?
|
|
763
|
+
Claude: [executes memorybank_search({ projectId: "my-app", query: "authentication login users" })]
|
|
764
764
|
|
|
765
|
-
|
|
765
|
+
Authentication is implemented in src/auth/authService.ts (lines 23-87):
|
|
766
766
|
|
|
767
|
-
[
|
|
767
|
+
[Found code]
|
|
768
768
|
|
|
769
|
-
|
|
770
|
-
|
|
769
|
+
The system uses JWT tokens with refresh token rotation.
|
|
770
|
+
Validation is done in the middleware src/middleware/auth.ts.
|
|
771
771
|
```
|
|
772
772
|
|
|
773
|
-
### 3.
|
|
773
|
+
### 3. Cross-Project Query
|
|
774
774
|
|
|
775
775
|
```
|
|
776
|
-
|
|
777
|
-
|
|
776
|
+
User: I'm working on "frontend-v2" but I want to see how pagination was done
|
|
777
|
+
in the "admin-dashboard" project
|
|
778
778
|
|
|
779
|
-
Claude: [
|
|
779
|
+
Claude: [executes memorybank_search({
|
|
780
780
|
projectId: "admin-dashboard",
|
|
781
|
-
query: "
|
|
781
|
+
query: "pagination table listing"
|
|
782
782
|
})]
|
|
783
783
|
|
|
784
|
-
|
|
785
|
-
[
|
|
784
|
+
In admin-dashboard, pagination was implemented like this...
|
|
785
|
+
[Shows code from the other project]
|
|
786
786
|
|
|
787
|
-
|
|
787
|
+
Would you like me to implement something similar in frontend-v2?
|
|
788
788
|
```
|
|
789
789
|
|
|
790
|
-
### 4.
|
|
790
|
+
### 4. Documentation Generation
|
|
791
791
|
|
|
792
792
|
```
|
|
793
|
-
|
|
794
|
-
Claude: [
|
|
793
|
+
User: Generate project documentation for new developers
|
|
794
|
+
Claude: [executes memorybank_generate_project_docs({ projectId: "my-app" })]
|
|
795
795
|
|
|
796
|
-
|
|
797
|
-
- projectBrief.md:
|
|
798
|
-
- systemPatterns.md:
|
|
799
|
-
- techContext.md:
|
|
796
|
+
I've generated 6 project knowledge documents:
|
|
797
|
+
- projectBrief.md: General description
|
|
798
|
+
- systemPatterns.md: Architecture and patterns
|
|
799
|
+
- techContext.md: Tech stack
|
|
800
800
|
...
|
|
801
801
|
|
|
802
|
-
|
|
802
|
+
You can query them anytime with memorybank_get_project_docs
|
|
803
803
|
```
|
|
804
804
|
|
|
805
805
|
---
|
|
806
806
|
|
|
807
|
-
## 🔧
|
|
807
|
+
## 🔧 Configuration Files
|
|
808
808
|
|
|
809
809
|
### `.memoryignore`
|
|
810
810
|
|
|
811
|
-
Similar
|
|
811
|
+
Similar to `.gitignore`, specifies patterns to exclude from indexing:
|
|
812
812
|
|
|
813
813
|
```bash
|
|
814
|
-
#
|
|
814
|
+
# Dependencies
|
|
815
815
|
node_modules/
|
|
816
816
|
vendor/
|
|
817
817
|
|
|
@@ -836,184 +836,184 @@ build/
|
|
|
836
836
|
*.mp4
|
|
837
837
|
```
|
|
838
838
|
|
|
839
|
-
###
|
|
839
|
+
### Respecting `.gitignore`
|
|
840
840
|
|
|
841
|
-
Memory Bank **
|
|
841
|
+
Memory Bank **automatically respects** `.gitignore` patterns in your project, in addition to `.memoryignore` patterns.
|
|
842
842
|
|
|
843
843
|
---
|
|
844
844
|
|
|
845
|
-
## 💰
|
|
845
|
+
## 💰 OpenAI Costs
|
|
846
846
|
|
|
847
|
-
Memory Bank
|
|
847
|
+
Memory Bank uses `text-embedding-3-small` which is very economical:
|
|
848
848
|
|
|
849
|
-
- **
|
|
850
|
-
- **
|
|
851
|
-
- **Cache**:
|
|
852
|
-
- **Incremental**:
|
|
849
|
+
- **Embedding price**: ~$0.00002 per 1K tokens
|
|
850
|
+
- **Example**: 10,000 files × 1,000 average tokens = **~$0.20**
|
|
851
|
+
- **Cache**: Embeddings are cached, only regenerated if code changes
|
|
852
|
+
- **Incremental**: Only modified files are reindexed
|
|
853
853
|
|
|
854
|
-
**
|
|
854
|
+
**Searches are extremely cheap** (only 1 embedding per query).
|
|
855
855
|
|
|
856
|
-
**
|
|
856
|
+
**AI Documentation** uses reasoning models which are more expensive but only run when explicitly requested.
|
|
857
857
|
|
|
858
858
|
---
|
|
859
859
|
|
|
860
860
|
## 🧪 Testing
|
|
861
861
|
|
|
862
862
|
```bash
|
|
863
|
-
#
|
|
863
|
+
# Run tests
|
|
864
864
|
npm test
|
|
865
865
|
|
|
866
|
-
# Tests
|
|
866
|
+
# Tests with coverage
|
|
867
867
|
npm test -- --coverage
|
|
868
868
|
```
|
|
869
869
|
|
|
870
870
|
---
|
|
871
871
|
|
|
872
|
-
## 🔐
|
|
872
|
+
## 🔐 Security and Privacy
|
|
873
873
|
|
|
874
|
-
- ✅ **
|
|
875
|
-
- ✅ **
|
|
876
|
-
- ✅ **
|
|
877
|
-
- ✅ **
|
|
878
|
-
- ✅ **API key
|
|
874
|
+
- ✅ **Local vector store**: LanceDB runs on your machine
|
|
875
|
+
- ✅ **No telemetry**: We don't send data to external servers
|
|
876
|
+
- ✅ **Embeddings only**: OpenAI only sees code text, not sensitive metadata
|
|
877
|
+
- ✅ **Respects .gitignore**: Ignored files are not indexed
|
|
878
|
+
- ✅ **Secure API key**: Read from environment variables, never hardcoded
|
|
879
879
|
|
|
880
|
-
###
|
|
880
|
+
### Recommendations
|
|
881
881
|
|
|
882
|
-
1. **
|
|
883
|
-
2. **
|
|
884
|
-
3. **API keys
|
|
885
|
-
4. **
|
|
882
|
+
1. **Don't push `.memorybank/` to git** (already in .gitignore)
|
|
883
|
+
2. **Use `.memoryignore`** to exclude sensitive files
|
|
884
|
+
3. **API keys in environment variables**, never in code
|
|
885
|
+
4. **Verify `.env` is in .gitignore**
|
|
886
886
|
|
|
887
887
|
---
|
|
888
888
|
|
|
889
|
-
## 🐛
|
|
889
|
+
## 🐛 Troubleshooting
|
|
890
890
|
|
|
891
891
|
### Error: "OPENAI_API_KEY is required"
|
|
892
892
|
|
|
893
|
-
**
|
|
893
|
+
**Solution**: Configure your API key in the MCP environment variables.
|
|
894
894
|
|
|
895
895
|
### Error: "No files found to index"
|
|
896
896
|
|
|
897
|
-
**
|
|
898
|
-
1.
|
|
899
|
-
2.
|
|
900
|
-
3. No
|
|
897
|
+
**Possible causes**:
|
|
898
|
+
1. Directory is empty
|
|
899
|
+
2. All files are in .gitignore/.memoryignore
|
|
900
|
+
3. No recognized code files
|
|
901
901
|
|
|
902
|
-
###
|
|
902
|
+
### Searches return irrelevant results
|
|
903
903
|
|
|
904
|
-
**
|
|
905
|
-
1. **
|
|
906
|
-
2. **
|
|
907
|
-
3. **
|
|
908
|
-
4. **
|
|
904
|
+
**Solutions**:
|
|
905
|
+
1. **Increase `minScore`**: Use 0.8 or 0.9 for more precise results
|
|
906
|
+
2. **Use filters**: `filterByFile` or `filterByLanguage`
|
|
907
|
+
3. **Rephrase query**: Be more specific and descriptive
|
|
908
|
+
4. **Reindex**: `memorybank_index_code({ path: "..." })` (automatically detects changes by hash)
|
|
909
909
|
|
|
910
910
|
### Error: "projectId is required"
|
|
911
911
|
|
|
912
|
-
**
|
|
912
|
+
**Solution**: All tools require `projectId`. Define `projectId` in your `AGENTS.md` file so the agent uses it consistently.
|
|
913
913
|
|
|
914
|
-
###
|
|
914
|
+
### Outdated Index
|
|
915
915
|
|
|
916
916
|
```json
|
|
917
917
|
memorybank_get_stats({})
|
|
918
918
|
```
|
|
919
919
|
|
|
920
|
-
|
|
920
|
+
If `pendingFiles` shows pending files, reindex the directory:
|
|
921
921
|
|
|
922
922
|
```json
|
|
923
923
|
{
|
|
924
924
|
"projectId": "my-project",
|
|
925
|
-
"path": "C:/workspaces/
|
|
925
|
+
"path": "C:/workspaces/my-project/src"
|
|
926
926
|
}
|
|
927
927
|
```
|
|
928
928
|
|
|
929
|
-
|
|
929
|
+
The system automatically detects changes by hash. Only use `forceReindex: true` if you need to regenerate embeddings even without changes.
|
|
930
930
|
|
|
931
931
|
---
|
|
932
932
|
|
|
933
|
-
## 📖
|
|
933
|
+
## 📖 Additional Documentation
|
|
934
934
|
|
|
935
|
-
###
|
|
935
|
+
### Instruction Templates
|
|
936
936
|
|
|
937
|
-
**
|
|
938
|
-
- [AGENTS.basic.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/AGENTS.basic.md) -
|
|
939
|
-
- [AGENTS.auto-index.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/AGENTS.auto-index.md) -
|
|
940
|
-
- [AGENTS.sandboxed.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/AGENTS.sandboxed.md) -
|
|
937
|
+
**AGENTS.md Format** (multi-agent standard):
|
|
938
|
+
- [AGENTS.basic.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/AGENTS.basic.md) - Basic mode (manual indexing)
|
|
939
|
+
- [AGENTS.auto-index.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/AGENTS.auto-index.md) - Auto-index mode
|
|
940
|
+
- [AGENTS.sandboxed.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/AGENTS.sandboxed.md) - Sandboxed mode (no direct file access)
|
|
941
941
|
|
|
942
|
-
**
|
|
943
|
-
- [copilot-instructions.basic.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/vscode/copilot-instructions.basic.md) -
|
|
944
|
-
- [copilot-instructions.auto-index.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/vscode/copilot-instructions.auto-index.md) -
|
|
945
|
-
- [copilot-instructions.sandboxed.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/vscode/copilot-instructions.sandboxed.md) -
|
|
946
|
-
- [memory-bank.instructions.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/vscode/memory-bank.instructions.md) -
|
|
942
|
+
**VS Code / Copilot Format**:
|
|
943
|
+
- [copilot-instructions.basic.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/vscode/copilot-instructions.basic.md) - Basic mode
|
|
944
|
+
- [copilot-instructions.auto-index.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/vscode/copilot-instructions.auto-index.md) - Auto-index mode
|
|
945
|
+
- [copilot-instructions.sandboxed.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/vscode/copilot-instructions.sandboxed.md) - Sandboxed mode
|
|
946
|
+
- [memory-bank.instructions.md](https://github.com/gcorroto/memory-bank-mcp/blob/main/templates/vscode/memory-bank.instructions.md) - Conditional instructions
|
|
947
947
|
|
|
948
948
|
---
|
|
949
949
|
|
|
950
|
-
## 🤝
|
|
950
|
+
## 🤝 Contributing
|
|
951
951
|
|
|
952
|
-
|
|
952
|
+
Contributions are welcome!
|
|
953
953
|
|
|
954
|
-
1. Fork
|
|
955
|
-
2.
|
|
956
|
-
3. Commit
|
|
957
|
-
4. Push
|
|
958
|
-
5.
|
|
954
|
+
1. Fork the project
|
|
955
|
+
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
|
|
956
|
+
3. Commit changes (`git commit -m 'Add some AmazingFeature'`)
|
|
957
|
+
4. Push to branch (`git push origin feature/AmazingFeature`)
|
|
958
|
+
5. Open a Pull Request
|
|
959
959
|
|
|
960
960
|
---
|
|
961
961
|
|
|
962
|
-
## 🎓
|
|
962
|
+
## 🎓 Inspiration
|
|
963
963
|
|
|
964
|
-
|
|
964
|
+
This project combines the best concepts from two complementary approaches:
|
|
965
965
|
|
|
966
|
-
### Cursor IDE -
|
|
966
|
+
### Cursor IDE - Semantic Indexing
|
|
967
967
|
|
|
968
|
-
|
|
968
|
+
The vector indexing and semantic search system is inspired by how Cursor IDE handles code memory:
|
|
969
969
|
|
|
970
|
-
- [Advanced Cursor: Use the Memory Bank](https://medium.com/codetodeploy/advanced-cursor-use-the-memory-bank-to-eliminate-hallucination-affd3fbeefa3) -
|
|
971
|
-
- [How Cursor Indexes Codebases Fast](https://read.engineerscodex.com/p/how-cursor-indexes-codebases-fast) -
|
|
970
|
+
- [Advanced Cursor: Use the Memory Bank](https://medium.com/codetodeploy/advanced-cursor-use-the-memory-bank-to-eliminate-hallucination-affd3fbeefa3) - Eliminate hallucinations with persistent memory
|
|
971
|
+
- [How Cursor Indexes Codebases Fast](https://read.engineerscodex.com/p/how-cursor-indexes-codebases-fast) - Efficient indexing techniques
|
|
972
972
|
|
|
973
|
-
### Cline -
|
|
973
|
+
### Cline - Structured Project Documentation
|
|
974
974
|
|
|
975
|
-
|
|
975
|
+
The **Project Knowledge Layer** system (structured markdown documents) is inspired by the Cline Memory Bank approach:
|
|
976
976
|
|
|
977
|
-
- [Cline MCP Memory Bank](https://github.com/dazeb/cline-mcp-memory-bank) -
|
|
978
|
-
- [Cline Memory Bank Custom Instructions](https://gist.github.com/zoharbabin/441e8e8b719a444f26b34bd0b189b283) -
|
|
977
|
+
- [Cline MCP Memory Bank](https://github.com/dazeb/cline-mcp-memory-bank) - Reference Memory Bank implementation for Cline
|
|
978
|
+
- [Cline Memory Bank Custom Instructions](https://gist.github.com/zoharbabin/441e8e8b719a444f26b34bd0b189b283) - Custom instructions for using Memory Bank
|
|
979
979
|
|
|
980
|
-
**
|
|
981
|
-
|
|
|
982
|
-
|
|
983
|
-
| `projectBrief.md` |
|
|
984
|
-
| `productContext.md` |
|
|
985
|
-
| `activeContext.md` |
|
|
986
|
-
| `systemPatterns.md` |
|
|
987
|
-
| `techContext.md` |
|
|
988
|
-
| `progress.md` |
|
|
980
|
+
**Documents from the Cline approach we adopted:**
|
|
981
|
+
| Document | Purpose |
|
|
982
|
+
|----------|---------|
|
|
983
|
+
| `projectBrief.md` | Project requirements and scope |
|
|
984
|
+
| `productContext.md` | Purpose, target users, problems solved |
|
|
985
|
+
| `activeContext.md` | Current tasks, recent changes, next steps |
|
|
986
|
+
| `systemPatterns.md` | Architectural decisions, patterns, relationships |
|
|
987
|
+
| `techContext.md` | Tech stack, dependencies, configurations |
|
|
988
|
+
| `progress.md` | Milestones, overall status, known issues |
|
|
989
989
|
|
|
990
|
-
###
|
|
990
|
+
### Our Contribution
|
|
991
991
|
|
|
992
|
-
Memory Bank MCP **
|
|
992
|
+
Memory Bank MCP **merges both approaches**:
|
|
993
993
|
|
|
994
|
-
1. **
|
|
995
|
-
2. **
|
|
996
|
-
3. **Multi-
|
|
994
|
+
1. **Semantic Search** (Cursor-style): Vector embeddings + LanceDB to find relevant code instantly
|
|
995
|
+
2. **Structured Documentation** (Cline-style): 6 AI-generated markdown documents providing global context
|
|
996
|
+
3. **Multi-Project**: Unique capability to query multiple indexed projects from any workspace
|
|
997
997
|
|
|
998
|
-
|
|
998
|
+
This combination allows agents to have both **precision** (semantic search) and **global understanding** (structured documentation).
|
|
999
999
|
|
|
1000
1000
|
---
|
|
1001
1001
|
|
|
1002
|
-
## 📜
|
|
1002
|
+
## 📜 License
|
|
1003
1003
|
|
|
1004
|
-
|
|
1004
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
1005
1005
|
|
|
1006
1006
|
---
|
|
1007
1007
|
|
|
1008
|
-
## 🆘
|
|
1008
|
+
## 🆘 Support
|
|
1009
1009
|
|
|
1010
1010
|
- **Issues**: [GitHub Issues](https://github.com/gcorroto/memory-bank-mcp/issues)
|
|
1011
|
-
- **
|
|
1012
|
-
- **OpenAI API**: [
|
|
1013
|
-
- **LanceDB**: [
|
|
1011
|
+
- **Documentation**: [Project Wiki](https://github.com/gcorroto/memory-bank-mcp/wiki)
|
|
1012
|
+
- **OpenAI API**: [Official Documentation](https://platform.openai.com/docs)
|
|
1013
|
+
- **LanceDB**: [Documentation](https://lancedb.github.io/lancedb/)
|
|
1014
1014
|
|
|
1015
1015
|
---
|
|
1016
1016
|
|
|
1017
|
-
⭐
|
|
1017
|
+
⭐ If you find this project useful, consider giving it a star!
|
|
1018
1018
|
|
|
1019
|
-
**
|
|
1019
|
+
**Made with ❤️ for the AI coding assistants community**
|