local-agent-context

A local MCP server that gives AI coding agents persistent memory and context across sessions. Works with VS Code (Copilot), Cursor, Claude, and any MCP-compatible client.

Why?

Every time you start a new conversation with an AI coding agent, it forgets everything. This server gives agents a local, fast, searchable memory backed by SQLite — so they remember your project conventions, past decisions, active tasks, and lessons learned.

Related MCP server: local-memory-mcp

Quick Start

Global Setup (Recommended)

Configure once — works across all projects. Agents pass the workspace path dynamically.

VS Code (GitHub Copilot) — add to User Settings (MCP: Open User Configuration):

{
  "servers": {
    "agent-context": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "local-agent-context@latest"]
    }
  }
}

Cursor — add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "agent-context": {
      "command": "npx",
      "args": ["-y", "local-agent-context@latest"]
    }
  }
}

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "agent-context": {
      "command": "npx",
      "args": ["-y", "local-agent-context@latest"]
    }
  }
}

Per-Project Setup (Alternative)

If you prefer a fixed workspace, pass --workspace at startup:

VS Code — add to .vscode/mcp.json:

{
  "servers": {
    "agent-context": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "local-agent-context@latest", "--workspace", "${workspaceFolder}"]
    }
  }
}

How It Works

Name-based workspaces: Every tool accepts an optional workspace parameter — the workspace or project name from your IDE (e.g., "my-app"). If a full path is passed instead, the basename is extracted automatically. The server lazily opens and caches workspace databases on demand.

Fallback chain: Tool workspace arg → --workspace CLI flag → WORKSPACE_PATH env var → global-only mode.

Centralized storage (nothing pollutes your project directories):

• Workspace memories: ~/.local-agent-context/workspaces/<name>/memory.db

• Global memory: ~/.local-agent-context/global.db

Both are SQLite databases with FTS5 full-text search.

Tools (10)

All tools accept an optional workspace parameter — the project name (e.g., "my-app") or path. Agents should pass the IDE's workspace/project name.

Core Memory

Context

Session Lifecycle

Shortcuts

Memory Types

Resources (3)

Typical Agent Workflow

1. Session start: Agent calls start_session with workspace → gets full project briefing

2. During work: Agent uses store_memory, log_decision, add_lesson with workspace to persist context

3. Searching: Agent uses recall with workspace to find relevant past memories

4. Session end: Agent calls end_session with workspace and a summary

Configuration

The server accepts these optional startup flags:

• --workspace <path> — default workspace path (used when tools don't pass workspace)

• WORKSPACE_PATH env var — alternative to --workspace

If neither is set, the server runs in global-only mode until agents pass workspace in tool calls.

Agent Instructions

Copy INSTRUCTIONS.md into your IDE's instruction system so agents automatically use this server:

This teaches the agent to call start_session at the start of every conversation, store decisions/conventions/lessons as they arise, and call end_session with a summary at the end.

Development

git clone https://github.com/yourname/local-agent-context
cd local-agent-context
npm install
npm run build
node dist/index.js --workspace /path/to/project

License

MIT