# alaya-mcp

Local memory engine for AI coding agents that builds a knowledge graph in SQLite and prunes stale memories using cognitive decay.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 18
- Author: SecurityRonin
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/SecurityRonin/alaya/tree/HEAD/npm/alaya-mcp
- Updated: 2026-07-16
- HTML: https://affpapa.org/en/nevibecode/mcp/alaya-mcp

## What it does

alaya-mcp runs an embeddable Rust memory core inside a local SQLite file at `~/.alaya/memory.db`. It captures conversation episodes and maps extracted entities into an associative graph.

Memory handling mimics biological principles. Retrieved items form stronger associations through Hebbian rules, while unaccessed entries decay under Bjork dual-strength logic. The tool exposes operations like `remember`, `recall`, and `neighbors`.

External LLM credentials remain optional. When vector embeddings are missing, the engine falls back to BM25 search and lets the agent handle extraction.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `ALAYA_LLM_API_KEY`, `ALAYA_LLM_API_URL`, `ALAYA_LLM_MODEL`, `ALAYA_DB` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env ALAYA_LLM_API_KEY=<ALAYA_LLM_API_KEY> --env ALAYA_LLM_API_URL=<ALAYA_LLM_API_URL> --env ALAYA_LLM_MODEL=<ALAYA_LLM_MODEL> --env ALAYA_DB=<ALAYA_DB> --transport stdio alaya-mcp -- npx -y alaya-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add alaya-mcp --env ALAYA_LLM_API_KEY=<ALAYA_LLM_API_KEY> --env ALAYA_LLM_API_URL=<ALAYA_LLM_API_URL> --env ALAYA_LLM_MODEL=<ALAYA_LLM_MODEL> --env ALAYA_DB=<ALAYA_DB> -- npx -y alaya-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "alaya-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "alaya-mcp"
            ],
            "env": {
                "ALAYA_LLM_API_KEY": "<ALAYA_LLM_API_KEY>",
                "ALAYA_LLM_API_URL": "<ALAYA_LLM_API_URL>",
                "ALAYA_LLM_MODEL": "<ALAYA_LLM_MODEL>",
                "ALAYA_DB": "<ALAYA_DB>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "alaya-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "alaya-mcp"
            ],
            "env": {
                "ALAYA_LLM_API_KEY": "<ALAYA_LLM_API_KEY>",
                "ALAYA_LLM_API_URL": "<ALAYA_LLM_API_URL>",
                "ALAYA_LLM_MODEL": "<ALAYA_LLM_MODEL>",
                "ALAYA_DB": "<ALAYA_DB>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e ALAYA_LLM_API_KEY=<ALAYA_LLM_API_KEY> -e ALAYA_LLM_API_URL=<ALAYA_LLM_API_URL> -e ALAYA_LLM_MODEL=<ALAYA_LLM_MODEL> -e ALAYA_DB=<ALAYA_DB> alaya-mcp npx -y alaya-mcp
```
Replace <…> with your own values

## When to use it
- retrieve relevant past facts without sending full conversation transcripts
- organize assistant context into an associative SQLite graph
- prune stale details automatically with dual-strength decay
- inspect relationships between concepts using neighbors

## Example prompts
- Recall our previous decisions regarding authentication architecture via alaya.
- Save this discussion into alaya and update concept links.
- Run the alaya lifecycle routine to maintain memory weights.

## Similar
- [Local Memory](https://affpapa.org/en/nevibecode/mcp/local-memory.md) — MCP server · ★ 15
- [kairn](https://affpapa.org/en/nevibecode/mcp/kairn.md) — MCP server · ★ 13
- [AitherOS ADK](https://affpapa.org/en/nevibecode/mcp/aitheros-adk.md) — MCP server · ★ 11
- [Waggle-mcp](https://affpapa.org/en/nevibecode/mcp/waggle-mcp.md) — MCP server · ★ 44
- [yantrikdb-mcp](https://affpapa.org/en/nevibecode/mcp/yantrikdb-mcp.md) — MCP server · ★ 25
- [agentdb-query](https://affpapa.org/en/nevibecode/skills/agentdb-query.md) — skill · 745 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md