light-agent-memory-mcp-server

MCP server for persistent agent memory — projects, preferences, and session learnings stored in a local SQLite database.

Harness-agnostic. Works with any MCP-compatible client: opencode, Claude Desktop, Cursor, Windsurf, etc.

Install

npm install -g light-agent-memory-mcp-server

Or use directly with npx (no install needed):

npx light-agent-memory-mcp-server

Configure

Add to your MCP client's config:

opencode (~/.config/opencode/opencode.json):

{
  "mcp": {
    "memory": {
      "type": "local",
      "command": ["npx", "-y", "light-agent-memory-mcp-server"],
      "enabled": true
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "light-agent-memory-mcp-server"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "light-agent-memory-mcp-server"]
    }
  }
}

Custom database path

npx light-agent-memory-mcp-server --db /path/to/custom.db

Tools

Project Memory

Tool	Description
memory_project_save	Save/update project context (tech stack, architecture, conventions)
memory_project_get	Get project details by name
memory_project_list	List all saved projects

Preference Memory

Tool	Description
memory_pref_save	Save/update a personal coding preference
memory_pref_get	Get a preference by key
memory_pref_list	List preferences (optionally filtered by category)

Learning Memory

Tool	Description
memory_learning_save	Record a session learning (solution, insight, bug note)
memory_learning_search	Search learnings by keyword

Generic

Tool	Description
memory_save	Unified save (auto-routes by type)
memory_search	Cross-type search by keyword
memory_delete	Delete a memory by type and ID
memory_list	List all memories with pagination and stats

Examples

Save a project:

memory_project_save({
  name: "my-app",
  path: "/home/user/projects/my-app",
  tech_stack: ["TypeScript", "React", "SQLite"],
  architecture: "Monorepo with pnpm workspaces, plugin-based architecture",
  conventions: "ESM-only, strict TypeScript, no comments in code"
})

Save a preference:

memory_pref_save({
  key: "language.typescript.style",
  value: "Always use ESM imports, strict mode, and prefer readonly types",
  category: "language"
})

Record a learning:

memory_learning_save({
  title: "Fix SQLite WAL mode deadlock",
  content: "When using WAL mode in SQLite, set busy_timeout to 5000ms to avoid SQLITE_BUSY errors under concurrent reads.",
  project_name: "my-app",
  tags: ["sqlite", "debugging", "concurrency"]
})

Search all memories:

memory_search({ query: "SQLite" })

Database

Data is stored in ~/.agent-memory/memory.db by default (SQLite via Node.js built-in node:sqlite). The database is created automatically on first run.

Schema

• projects — id, name (unique), path, tech_stack (JSON), architecture, conventions, notes, timestamps
• preferences — id, key (unique), value, category, timestamps
• learnings — id, title, content, project_name, tags (JSON), timestamps

Development

git clone https://github.com/AliYar-Khan/light-agent-memory-mcp-server.git
cd light-agent-memory-mcp-server
npm install
npm run build
npm run dev  # runs with tsx, no build step

License

MIT