Copilot Memory Store

A local JSON memory store for context engineering with GitHub Copilot and MCP clients.

Documentation

| Guide | When to read | |-------|--------------| | examples/QUICKSTART.md | Start here - npm commands cheatsheet | | examples/COPILOT_CHAT_EXAMPLES.md | 50+ copy-paste prompts for Copilot Chat | | docs/CONTEXT_MEMORY_TYPES.md | Deep dive into LLM memory types and how this project works | | docs/CODE_WALKTHROUGH.md | Architectural overview with flow diagrams | | docs/CLI_GUIDE.md | Interactive REPL command reference | | docs/COPILOT_GUIDE.md | Using the memory tools from GitHub Copilot |

Features

• CLI (memory>) - Interactive REPL for managing memories
• MCP Server - Stdio server exposing tools, resources, and prompts
• Custom VS Code Agent - Pre-configured "Memory" agent for natural language usage
• Context Compression - Budget-constrained context injection with optional LLM summarization
• Auto-Keywords - Automatic keyword extraction for improved search relevance

Why This Exists

LLMs have limited context windows. This tool helps you:

1. Store important information as searchable memories with auto-extracted keywords
2. Search memories by relevance scoring (keywords + tags + recency)
3. Compress relevant memories into a character budget for context injection

Perfect for teaching context engineering - the art of fitting the right information into limited LLM context.

Quick Start

# Install dependencies
npm install

# Copy environment config (tweak MEMORY_PATH / DeepSeek settings as needed)
cp .env.example .env

# Build the project
npm run build

# Run the CLI
npm run dev

# Or run the MCP server
npm run mcp

# Debug presets live in `.vscode/launch.json` (Run → Start Debugging → pick a config)

Heads-up: project-memory.json contains a few demo memories for workshops. Delete it (or point MEMORY_PATH elsewhere) before your first real run if you want to start with an empty store.

VS Code GitHub Copilot Integration

1. Build the project

npm run build

2. Configure MCP server

The project includes a pre-configured .vscode/mcp.json:

{
  "servers": {
    "copilot-memory": {
      "type": "stdio",
      "command": "node",
      "args": ["./dist/mcp-server.js"],
      "env": {
        "MEMORY_PATH": "project-memory.json"
      }
    }
  }
}

Run npm run build whenever you change the server so the compiled dist/mcp-server.js stays current.

3. Use the Memory Agent (Recommended)

The project includes a custom Memory agent at .github/agents/memory-agent.agent.md that makes using the memory tools natural.

To use:

1. Open Copilot Chat in VS Code
2. Click the agent dropdown (shows "Agent", "Ask", etc.)
3. Select "Memory"
4. Chat naturally!

Example conversations:

You: Remember that I prefer functional components over class components
Agent: [Calls memory_write] Saved your preference for functional React components.

You: What preferences do I have stored?
Agent: [Calls memory_search] Based on your stored memories, you prefer...

You: Help me refactor auth.ts
Agent: [Calls memory_search first for context] I found some relevant context about your authentication preferences...

4. Direct Tool References (Alternative)

You can also reference tools directly with #:

#memory_write text: "We use PostgreSQL" tags: ["decision", "database"]
#memory_search query: "database"

5. Reload VS Code

After any configuration changes, reload VS Code:

• Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
• Run "Developer: Reload Window"

MCP Server Features

Tools (7)

| Tool | Description | |------|-------------| | memory_write | Add, save, store, or remember information to project memory | | memory_search | Search, find, recall, or look up information from project memory | | memory_compress | Create compact context from relevant memories within a budget | | memory_delete | Soft-delete a memory (tombstone, recoverable) | | memory_purge | Hard-delete by id, tag, or substring match | | memory_export | Export all records as JSON | | inject_context | Auto-inject shaped context for a task (uses DeepSeek LLM) |

Resources (2)

| Resource | URI | Description | |----------|-----|-------------| | stats | memory://stats | Live statistics (counts, top tags) | | recent | memory://recent | Last 10 memories added |

Prompts (3)

Note: VS Code GitHub Copilot does not currently support MCP prompts. Use the MCP Inspector or other MCP clients to test prompts.

| Prompt | Description | |--------|-------------| | summarize-memories | Generate a summary of memories on a topic | | remember-decision | Structured template for architectural decisions | | inject-context | Auto-inject relevant memories as context for a task |

Context Shaping with DeepSeek

The inject-context prompt supports LLM-powered context shaping via DeepSeek:

{
  "task": "refactor the auth module",
  "budget": 1500,
  "shape": true
}

When shape: true:

• Raw memories are transformed into task-specific actionable guidance
• Output is structured with clear headers (## Context for:, ### Key Constraints)
• Irrelevant memories are filtered out
• Falls back to deterministic compression if DeepSeek isn't configured

This makes context injection more intuitive - instead of raw memory dumps, you get focused guidance like:

## Context for: Auth Module Refactor

### Preferences
- Use JWT tokens (15min access, 7 day refresh)
- Passwords hashed with bcrypt, cost factor 12

### Key Constraints
- Three-layer architecture: Controller → Service → Repository
- All validation via Zod at API boundary

Configuration

Edit .env:

# Required: where memories are stored
MEMORY_PATH=.copilot-memory.json

# Optional: for LLM-assisted compression
DEEPSEEK_API_KEY=your-key-here
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat

The MCP configuration in .vscode/mcp.json points at project-memory.json so you can ship a pre-filled sample store. Override MEMORY_PATH in your environment if you want the CLI and MCP server to share a different file.

MCP Inspector

Debug and test the MCP server interactively:

# Launch inspector (opens web UI)
npm run inspect

# Or with live TypeScript reloading
npm run inspect:dev

The inspector lets you:

• Browse all tools, resources, and prompts
• Execute tools and see responses
• View raw JSON-RPC message traffic

CLI Commands

See docs/CLI_GUIDE.md for detailed usage and examples.

| Command | Description | |---------|-------------| | add [--tags a,b] <text> | Add a memory | | search <query> [--limit N] [--raw] | Search memories | | compress <query> [--budget N] [--llm] | Compress for context | | delete <id> | Soft-delete | | purge --id/--tag/--match | Hard-delete | | export | Dump JSON | | stats | Show statistics |

Context Engineering Demo

The memory_compress tool demonstrates key context engineering concepts:

1. Relevance Scoring - Memories ranked by keyword matches + tag matches + recency
2. Budget Constraints - Fit context into character limits (200-8000 chars)
3. Deterministic Compression - Predictable truncation without LLM
4. LLM-Assisted Compression - Optional DeepSeek summarization for smarter compression

Architecture

.github/
├── agents/
│   └── memory-agent.agent.md  # Custom VS Code agent definition
├── prompts/                   # Reusable Copilot prompt files
│   ├── add-memory.prompt.md
│   ├── retrieve-memory.prompt.md
│   └── inject-memory.prompt.md
└── copilot-instructions.md    # Onboarding for AI coding agents
.vscode/
├── launch.json
├── mcp.json
└── settings.json
docs/
├── CODE_WALKTHROUGH.md   # Architecture walkthrough + diagrams
├── CLI_GUIDE.md          # CLI usage guide
└── COPILOT_GUIDE.md      # VS Code Copilot usage guide
examples/
├── QUICKSTART.md         # npm commands cheatsheet
├── COPILOT_CHAT_EXAMPLES.md  # 50+ prompt examples
└── scenarios/            # Pre-built memory files for workshops
    ├── react-developer.json
    ├── api-backend.json
    └── team-decisions.json
src/
├── cli.ts                # Interactive REPL
├── mcp-server.ts         # MCP stdio server (tools, resources, prompts)
├── memoryStore.ts        # Core storage, search, compression
└── deepseek.ts           # Optional LLM compression + context shaping

npm Scripts

| Script | Description | |--------|-------------| | npm run dev | Run CLI with tsx (dev mode) | | npm run build | Compile TypeScript to dist/ | | npm run mcp | Run MCP server with tsx | | npm run inspect | Launch MCP Inspector | | npm run inspect:dev | Inspector with tsx (live reload) |

Development Workflow

| Task | Recommended action | |------|--------------------| | Edit + run CLI locally | npm run dev or VS Code "CLI (TypeScript via tsx)" debug config | | Serve MCP tools to Copilot | npm run mcp during development; rebuild with npm run build for the dist-based config | | Explore MCP surface area | npm run inspect or npm run inspect:dev | | Update docs/instructions | Keep docs/ and .github/copilot-instructions.md in sync |

External Resources

• VS Code Custom Agents
• VS Code MCP Servers
• MCP Specification
• MCP TypeScript SDK
• MCP Inspector

Author

Tim Warner

• Website
• GitHub
• LinkedIn
• YouTube
• Bluesky
• Mastodon

License

MIT