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.

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

| Tool | Description | |------|-------------| | store_memory | Store a memory with type, title, content, tags, importance (1-10), and scope | | recall | Full-text search across all memories. Filter by type, tags, scope, status | | update_memory | Update any fields of an existing memory by ID | | delete_memory | Soft-delete (archive) or hard-delete a memory by ID | | list_memories | List memories with optional filters and pagination |

Context

| Tool | Description | |------|-------------| | get_context | Get a curated briefing: project info, active tasks, conventions, decisions, lessons, global prefs |

Session Lifecycle

| Tool | Description | |------|-------------| | start_session | Start a coding session. Returns full workspace context. Auto-closes any dangling sessions | | end_session | End session with a summary. Summary is stored as a searchable memory |

Shortcuts

| Tool | Description | |------|-------------| | log_decision | Store an architectural decision with rationale (importance defaults to 7) | | add_lesson | Record a lesson learned with optional context (importance defaults to 6) |

Memory Types

| Type | Use For | |------|---------| | project | Stack, structure, build commands, environment setup | | convention | Coding style, patterns, naming conventions | | decision | Architectural choices with rationale | | task | Active work items, TODOs, features in progress | | lesson | Gotchas, things that went wrong, best practices | | note | General-purpose notes | | session_summary | Auto-generated from end_session |

Resources (3)

| URI | Description | |-----|-------------| | context://workspace | Full workspace context (same as get_context) | | context://recent-sessions | Last 5 session summaries | | context://active-tasks | All active task memories |

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:

| IDE | Where to Add | |-----|-------------| | VS Code (Copilot) | Copy contents into .github/copilot-instructions.md, or save as .github/instructions/agent-memory.instructions.md | | Cursor | Copy contents into .cursorrules or .cursor/rules/agent-memory.mdc | | Claude Desktop | Paste into your Project Instructions |

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