MCP-Smart-Memory-Context

Persistent, structured memory for AI assistants — built on the Model Context Protocol. Stop re-explaining your project on every session. Let your AI remember what matters.

Table of Contents

• Why This Exists
• Architecture Overview
• Features
• Prerequisites
• Installation
• Configuration
• Available Tools
• Memory Categories
• Usage Examples
• Integration Guide
• Project Structure
• Contributing
• License

Why This Exists

Every AI coding session starts with the same problem: the model has no memory of yesterday.

You re-explain your stack. You re-state your conventions. You re-justify architectural decisions. This is waste — pure, measurable, painful waste.

MCP-Smart-Memory-Context solves this by providing a structured, queryable memory layer that persists across sessions. It integrates with Claude, Cursor, VS Code, and any MCP-compatible client through the standard Model Context Protocol interface.

Before this tool:

You: "We use pnpm, not npm. Functions must be ≤ 30 lines. No abbreviations."
Claude: [forgets this tomorrow]
You: [repeats the same thing next session]

After this tool:

Claude: [session start] → memory_search("project conventions")
        → returns: pnpm, 30-line limit, no abbreviations
        → applies them immediately, without being told

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                    MCP Client                           │
│         (Claude / Cursor / VS Code / Roo Code)          │
└────────────────────┬────────────────────────────────────┘
                     │  MCP Protocol (stdio / SSE)
                     ▼
┌─────────────────────────────────────────────────────────┐
│              smart-memory MCP Server                    │
│                                                         │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐  │
│  │  Tool Layer │  │ Context Mgr  │  │  Query Engine │  │
│  │             │  │              │  │               │  │
│  │ memory_store│  │ Token Budget │  │ Semantic Rank │  │
│  │ memory_srch │  │ Deduplication│  │ Tag Filtering │  │
│  │ memory_updt │  │ Importance   │  │ Project Scope │  │
│  │ memory_del  │  │ Scoring      │  │               │  │
│  └─────────────┘  └──────────────┘  └───────────────┘  │
│                          │                              │
└──────────────────────────┼──────────────────────────────┘
                           │
                     ┌─────▼──────┐
                     │  Storage   │
                     │  (SQLite / │
                     │   JSONL)   │
                     └────────────┘

The server exposes a clean, minimal tool surface to the model. Complexity is encapsulated inside the server — the model gets a simple, well-typed interface.

Features

Prerequisites

• Node.js ≥ 18.0.0 (LTS recommended)
• npm ≥ 9.0.0 or pnpm ≥ 8.0.0
• An MCP-compatible client (Claude Desktop, Claude Code, Cursor, VS Code with MCP extension)
• macOS, Linux, or Windows (WSL2 recommended on Windows)

Installation

Option 1 — Clone and build (recommended for contributors)

# 1. Clone the repository
git clone https://github.com/VoTrongHoang-Dyor/MCP-Smart-Memory-Context.git
cd MCP-Smart-Memory-Context

# 2. Install dependencies
npm install        # or: pnpm install

# 3. Build the server
npm run build      # outputs to ./dist

# 4. Verify the build
node dist/index.js --version

Option 2 — npx (zero-install, for end users)

npx mcp-smart-memory-context

Option 3 — Global install

npm install -g mcp-smart-memory-context
mcp-smart-memory-context --version

Configuration

Claude Desktop (claude_desktop_config.json)

Located at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "smart-memory": {
      "command": "node",
      "args": ["/absolute/path/to/MCP-Smart-Memory-Context/dist/index.js"],
      "env": {
        "MEMORY_DIR": "/absolute/path/to/your/memory-store",
        "LOG_LEVEL": "info",
        "MAX_RESULTS_DEFAULT": "5",
        "ENABLE_DEDUPLICATION": "true"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add smart-memory node /absolute/path/to/dist/index.js

Cursor / VS Code (.vscode/mcp.json)

{
  "servers": {
    "smart-memory": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "MEMORY_DIR": "/absolute/path/to/your/memory-store"
      }
    }
  }
}

Roo Code (cline_mcp_settings.json)

{
  "mcpServers": {
    "smart-memory": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "MEMORY_DIR": "/absolute/path/to/your/memory-store"
      },
      "disabled": false,
      "alwaysAllow": [
        "memory_search",
        "memory_list"
      ]
    }
  }
}

Environment Variables

Available Tools

The server exposes the following MCP tools to connected clients:

memory_store

Store a new memory entry.

memory_store({
  content: string,        // Required. The fact or decision to remember.
  category: Category,     // Required. See Memory Categories below.
  project: string,        // Required. Project slug, or "global".
  tags?: string[],        // Optional. For filtering.
  importance?: Importance // Optional. "high" | "medium" | "low". Default: "medium"
})

memory_search

Retrieve relevant memories by semantic query.

memory_search({
  query: string,          // Required. Natural language query.
  project?: string,       // Optional. Scope to a project. Default: current project.
  category?: Category,    // Optional. Filter by category.
  tags?: string[],        // Optional. Filter by tags.
  limit?: number          // Optional. Max results. Default: 5.
})

memory_update

Update an existing memory entry by ID.

memory_update({
  id: string,             // Required. The memory_id to update.
  content: string,        // Required. New content.
  change_reason?: string  // Optional but recommended. Why was this changed?
})

memory_delete

Delete a memory entry.

memory_delete({
  id: string              // Required. The memory_id to delete.
})

memory_list

List all memories for a project (paginated).

memory_list({
  project?: string,       // Optional. Filter by project.
  category?: Category,    // Optional. Filter by category.
  limit?: number,         // Optional. Default: 10.
  offset?: number         // Optional. For pagination. Default: 0.
})

Memory Categories

Usage Examples

Example 1 — First session setup

User: "Let's set up memory for my project. Stack: Next.js 15, Drizzle ORM, Postgres,
       Tailwind. We use pnpm. All components are server components unless marked 'use client'.
       Naming: kebab-case for files, PascalCase for components."

Claude: Storing project conventions...
  → memory_store(category="pattern", project="my-app", content="Stack: Next.js 15,
     Drizzle ORM, PostgreSQL, Tailwind CSS. Package manager: pnpm.", importance="high")
  → memory_store(category="pattern", project="my-app", content="All React components
     default to Server Components. Add 'use client' directive only when required.",
     importance="high")
  → memory_store(category="pattern", project="my-app", content="File naming: kebab-case.
     Component naming: PascalCase.", importance="medium")

  ✓ 3 memories saved for project 'my-app'.

Example 2 — Returning session, instant context recovery

[New session]
User: "Continue working on the auth module."

Claude: [memory_search(query="auth module my-app", project="my-app", limit=5)]
  → Found: Sprint 3 context, OAuth blocker, component conventions, stack preferences.

  "Resuming work on the auth module. Current state: OAuth provider approval pending.
   I'll implement the credential fallback path first. Using server components,
   Drizzle for DB access, pnpm for any installs."

Example 3 — Decision update

User: "We're switching from Drizzle to Prisma. Team decision."

Claude: [memory_search(query="ORM decision my-app")]
  → Found memory_id: "mem_a1b2c3" — Drizzle ORM decision.

  [memory_update(id="mem_a1b2c3", content="ORM: Prisma (migrated from Drizzle, 2026-04-17).
   Rationale: team familiarity, better Prisma Studio tooling.", change_reason="Team decision")]

  ✓ Memory updated. Future sessions will use Prisma context.

Integration Guide

Adding CLAUDE.md to your project

Place the CLAUDE.md file at the root of your repository. Claude will automatically read it when operating in that directory. It defines the binding operational rules for how Claude interacts with this MCP server.

your-project/
├── CLAUDE.md              ← rules for Claude behaviour in this repo
├── .vscode/
│   └── mcp.json           ← MCP server config for VS Code / Cursor
├── src/
└── ...

Recommended alwaysAllow settings

For smooth daily use, set these tools to auto-approve in your client:

"alwaysAllow": [
  "memory_search",
  "memory_list"
]

Require explicit approval for:

"requireApproval": [
  "memory_delete"
]

Token budget guidance

The server is designed to stay within a 2,000-token retrieval budget per query. For context-heavy projects, use category and tag filters to narrow results rather than increasing the limit parameter.

Project Structure

MCP-Smart-Memory-Context/
├── CLAUDE.md                  # Operational rules for Claude
├── README.md                  # This file
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts               # Server entry point
│   ├── server.ts              # MCP server definition
│   ├── tools/
│   │   ├── store.ts           # memory_store implementation
│   │   ├── search.ts          # memory_search implementation
│   │   ├── update.ts          # memory_update implementation
│   │   ├── delete.ts          # memory_delete implementation
│   │   └── list.ts            # memory_list implementation
│   ├── services/
│   │   ├── storage.ts         # Storage layer abstraction
│   │   ├── deduplication.ts   # Duplicate detection logic
│   │   └── ranking.ts         # Relevance scoring
│   ├── types/
│   │   └── index.ts           # TypeScript type definitions
│   └── config.ts              # Environment config
├── dist/                      # Compiled output (git-ignored)
└── tests/
    ├── tools/
    └── services/

Contributing

Contributions are welcome and held to a high standard.

Before submitting a pull request:

1. All tests must pass: npm test
2. TypeScript must compile without errors: npm run build
3. New features must include unit tests
4. Update CLAUDE.md if you change tool signatures or add new tools
5. Update this README.md if you add new configuration options

Please open an issue first for significant changes.

# Development setup
git clone https://github.com/VoTrongHoang-Dyor/MCP-Smart-Memory-Context.git
cd MCP-Smart-Memory-Context
npm install
npm run dev     # watch mode
npm test        # run test suite

Thao tác sử dụng MCP ? Cần tải bộ Rules để sử dụng MCP ?