# 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

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

Or use directly with npx (no install needed):

```bash
npx light-agent-memory-mcp-server
```

## Configure

Add to your MCP client's config:

**opencode** (`~/.config/opencode/opencode.json`):
```json
{
  "mcp": {
    "memory": {
      "type": "local",
      "command": ["npx", "-y", "light-agent-memory-mcp-server"],
      "enabled": true
    }
  }
}
```

**Claude Desktop** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "light-agent-memory-mcp-server"]
    }
  }
}
```

**Cursor** (`.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "light-agent-memory-mcp-server"]
    }
  }
}
```

### Custom database path

```bash
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

```bash
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