memory-bank-mcp

# Memory Bank — Copilot Instructions

> Auto-generated by Memory Bank extension. Edit freely to customize.

This project uses the Memory Bank MCP server to persist context across AI sessions.
You have access to Memory Bank MCP tools. USE THEM — they are not optional.

## Mandatory Workflow (every task, no exceptions)

### START of task
1. ⚠️ CALL THIS FIRST. Call `get_instructions` MCP tool to learn the full tool catalog and workflow (once per session)
2. Call `get_context_digest` to load current project state (tasks, issues, progress, decisions)
3. Read `system-patterns.md` (via `read_memory_bank_file`) to understand project conventions, architecture patterns, and coding standards
4. Use `graph_search` to find relevant knowledge graph entities

### DURING task
4. Call `track_progress` after completing milestones
5. Call `log_decision` when making architectural/design choices
6. Call `add_session_note` for observations, blockers, or questions

### END of task
7. Call `update_active_context` with updated tasks, issues, and next steps
8. Call `track_progress` with a final summary of what was accomplished
9. Update knowledge graph entities if project structure changed
10. Update `system-patterns.md` if new patterns, architecture, or conventions were introduced

## If Memory Bank contains placeholder text
If any core file contains `[Project description]` or `[Task 1]` style placeholders,
the Memory Bank has never been initialized. You MUST populate all core files with real
project data from the workspace before doing any other work.

## First-Time Initialization Procedure
When placeholder content is detected:
1. Scan workspace: package.json, README, config files, source directories
2. `write_memory_bank_file` for: product-context.md, active-context.md, progress.md, decision-log.md, system-patterns.md
3. `graph_upsert_entity` + `graph_add_observation` + `graph_link_entities` for major components
4. `add_session_note` → "Memory Bank initialized from workspace analysis."

## Available MCP Tools

### Context & Status
- `get_context_digest` — Compact summary (includes graph)
- `get_context_bundle` — All core files at once
- `get_memory_bank_status` — Current status
- `read_memory_bank_file` / `write_memory_bank_file` — Individual files
- `batch_read_files` / `batch_write_files` — Multiple files
- `search_memory_bank` — Full-text search

### Progress & Decisions
- `track_progress` — Log progress (type, summary, details, tags)
- `add_progress_entry` — Structured entry (feature/fix/refactor/docs/test/chore)
- `update_active_context` — Update tasks, issues, next steps
- `update_tasks` — Add, remove, or replace tasks
- `log_decision` — Record decisions with rationale
- `add_session_note` — Timestamped notes (observation/blocker/question/todo)

### Knowledge Graph
- `graph_search` — Search entities and relations
- `graph_open_nodes` — Subgraph by entity names
- `graph_upsert_entity` — Create/update entities
- `graph_add_observation` — Add observations to entities
- `graph_link_entities` / `graph_unlink_entities` — Manage relationships
- `graph_delete_entity` / `graph_delete_observation` — Remove data
- `graph_rebuild` / `graph_compact` — Maintenance

### Other
- `get_instructions` — Full tool catalog and workflow guide (call first!)
- `switch_mode` / `get_current_mode` — Mode management
- `list_stores` / `select_store` — Store management
- `create_backup` / `list_backups` / `restore_backup` — Backups
- `initialize_memory_bank` — Initialize at a path

## Valid Modes
The ONLY valid modes are: **architect**, **code**, **ask**, **debug**, **test**.
There is NO "full" mode. All tools are available in every mode — modes control
behavior guidelines (via .clinerules files), not tool access.

## Agent Skills

This project includes `.agents/skills/` with domain-specific expertise.
When a task falls within a skill's domain, read the skill file first:

| Skill | File | When to use |
|-------|------|-------------|
| bun-expert | `.agents/skills/bun-expert/SKILL.md` | Building, testing, or running with Bun runtime |
| code-quality | `.agents/skills/code-quality/SKILL.md` | Code reviews, refactoring, SOLID principles |
| testing-strategist | `.agents/skills/testing-strategist/SKILL.md` | Test strategy, coverage, TDD, test types |
| typescript-best-practices | `.agents/skills/typescript-best-practices/SKILL.md` | Reading or writing TypeScript/JavaScript files |
| vscode-extension-dev | `.agents/skills/vscode-extension-dev/SKILL.md` | VS Code extension development, webviews, CSP |

## Important Notes
- Keep your internal thought process private. Do NOT share it in the conversation.

## ⚠️ CRITICAL: Never Access memory-bank/ Directly

AI agents/LLMs must **NEVER** directly edit files in the `memory-bank/` folder
using file editing tools (`replace_string_in_file`, `create_file`, `write_file`)
or terminal commands (`echo`, `sed`, `cat >`).

**All interactions with Memory Bank files MUST go through the MCP server tools:**

| Operation | Tool(s) |
|---|---|
| Read files | `read_memory_bank_file`, `batch_read_files`, `get_context_bundle` |
| Write files | `write_memory_bank_file`, `batch_write_files` |
| Update context | `update_active_context`, `update_tasks` |
| Track progress | `track_progress`, `add_progress_entry` |
| Log decisions | `log_decision` |
| Session notes | `add_session_note` |
| Knowledge graph | `graph_upsert_entity`, `graph_add_observation`, `graph_link_entities`, etc. |
| Search | `search_memory_bank`, `graph_search` |

**Why?** The MCP server guarantees file integrity via ETag concurrency control,
atomic writes, content validation, and event logging. Direct edits bypass all of
these and can corrupt the Memory Bank state.