# alexa-memory-mcp

A Model Context Protocol (MCP) server that gives Alexa+ a persistent memory. Voice assistants forget everything between sessions: you tell them your dog's name on Monday and by Friday they have no idea. This project wraps a knowledge-graph memory engine (facts stored as subject/relation/object triples in a graph database, plus the raw memories they came from) behind four MCP tools, so an Alexa+ integration can learn facts once, recall them in any later session, forget on request, and report what it knows.

## Why Alexa+ needs this

Alexa+ integrations are built on the open MCP standard, but the standard only carries messages: there is no durable memory layer. Without one, every conversation starts from zero and personalization is impossible. alexa-memory-mcp plugs that gap with a persistent graph memory: tell the assistant something once ("my dog's name is Bruno"), and it stores a structured triple (my dog / has_name / Bruno) linked to the original statement. Later sessions ask questions against the graph, retrieve exactly the relevant facts, and answer from them instead of guessing. Forgetting is first-class too: `memory_forget` wipes an entity and everything attached to it, which is what privacy-conscious voice users expect.

## Architecture

```
 demo page (index.html + app.js)
        |
        |  HTTP (demo) / MCP over Streamable HTTP (Alexa+ clients)
        v
 FastMCP server (server.py)
        |
        v
 MemoryAgent (memgraph/agent.py) --- tell / ask / forget / stats
        |                                      |
        v                                      v
 InMemoryGraphStore or FalkorDB        LLM provider
 (zero-setup for demos /              (Gemini free tier, OpenAI-compatible,
  real graph DB in prod)               or FakeLLM offline)
```

The demo page talks to the same `MemoryAgent` the MCP tools use, so what you see in the browser is exactly what Alexa+ would get.

## Setup and run

Requirements: Python 3.10+.

```bash
cd alexa-memory-mcp
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Environment variables:

| Variable        | Meaning                                             | Default |
|-----------------|-----------------------------------------------------|---------|
| `MCP_PORT`      | Port the server listens on                          | `8765`  |
| `LLM_BACKEND`   | `gemini`, `openai`, or `fake`                       | auto-detect (gemini, then openai); `fake` = offline demo LLM |
| `GEMINI_API_KEY`| Google Gemini key (free tier works)                 | -       |
| `OPENAI_API_KEY`| Any OpenAI-compatible API key                       | -       |

Run offline (no keys, no database):

```bash
LLM_BACKEND=fake python server.py
```

Then open http://127.0.0.1:8765/ for the demo page: tell it a fact, ask about it later, watch the triple land in the graph.

For production memory, point the server at FalkorDB (`FALKORDB_HOST` / `FALKORDB_PORT` / `FALKORDB_PASSWORD`) and set a real `LLM_BACKEND` with the matching API key.

### Run the tests

```bash
python -m venv .venv && source .venv/bin/activate
pip install pytest
python -m pytest tests/ -v
```

## Tools

The four MCP tools exposed by `server.py`:

| Tool           | Input              | What it does                                              |
|----------------|--------------------|-----------------------------------------------------------|
| `memory_tell`  | `text: str`        | Extracts factual triples from a statement and stores them (plus the original memory). Returns the stored triples. |
| `memory_ask`   | `question: str`    | Plans graph lookups, retrieves relevant triples and memories, and answers using only those facts. |
| `memory_forget`| `name: str`        | Erases an entity and every triple and memory attached to it. Returns `true` if anything was removed. |
| `memory_stats` | (none)             | Reports counts of triples, memories, and entities in the store. |

Example session:

```
tell("my dog's name is Bruno")     -> [Triple(subject="my dog", relation="has_name", object="Bruno")]
ask("what's my dog's name?")       -> "Bruno"
stats()                            -> {"triples": 1, "memories": 1, "entities": 2}
forget("my dog")                   -> True
```

## Built during the hackathon window

Build log for the hackathon period (all work landed Oct 17, 2026, ahead of the Oct 23 deadline).

- **2026-10-17**: Scaffolded the project. Built the MCP server (server.py, FastMCP, spec 2025-11-25, Streamable HTTP, four tools). Vendored the memgraph knowledge-graph engine. Built the simulated Alexa+ web demo (demo/). Wrote the pytest suite (5 tests). Fixed: Gemini default model (gemini-2.0-flash 404s for new keys, moved to gemini-3.8-flash); recall fallback for coreference resolution ("my cat" -> "Whiskers"); 429 backoff retries; extract prompt has_name rule; answer prompt name-resolution guidance. Recorded the 66-second demo video. Published the repo (public, MIT). Submitted on Devpost (Alexa+ track + Open Source mini challenge).