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