Expand README, fix topics parsing

Author: abrookins

README.md

@@ -133,15 +133,29 @@ Agent Memory Server offers an MCP (Model Context Protocol) server interface powe
 
 ### Local Install
 
-1. Install the package and required dependencies:
+First, you'll need to download this repository. After you've downloaded it, you can install and run the servers.
+
+1. Install the package and required dependencies with pip, ideally into a virtual environment:
    ```bash
    pip install -e .
    ```
 
-2. Start both the REST API server and MCP server:
+**NOTE:** This project uses `uv` for dependency management, so if you have uv installed, you can run `uv sync` instead of `pip install ...` to install the project's dependencies.
+
+2 (a). The easiest way to start the REST API server and MCP server in SSE mode is to use Docker Compose. See the Docker Compose section of this file for more details.
+
+2 (b). You can also run the REST API and MCP servers directly:
+#### REST API
   ```bash
   python -m agent_memory_server.main
   ```
+#### MCP Server
+The MCP server can run in either SSE mode or stdio:
+  ```bash
+  python -m agent_memory_server.mcp <sse|stdio>
+  ```
+
+**NOTE:** With uv, just prefix the command with `uv`, e.g.: `uv run python -m agent_memory_server.mcp sse`.
 
 ### Docker Compose
 
@@ -161,6 +175,51 @@ To start the API using Docker Compose, follow these steps:
 6. To stop the containers, press Ctrl+C in the terminal and then run:
    docker-compose down
 
+## Using the MCP Server with Claude Desktop, Cursor, etc.
+You can use the MCP server that comes with this project in any application or SDK that supports MCP tools.
+
+### Claude
+<img src="claude.png">
+
+For example, with Claude, use the following configuration:
+  ```json
+  {
+    "mcpServers": {
+      "redis-memory-server": {
+          "command": "uv",
+          "args": [
+              "--directory",
+              "/ABSOLUTE/PATH/TO/REPO/DIRECTORY/agent-memory-server",
+              "run",
+              "python",
+              "-m",
+              "agent_memory_server.mcp",
+              "stdio"
+          ]
+      }
+    }
+  }
+  ```
+**NOTE:** On a Mac, this configuration requires that you use `brew install uv` to install uv. Probably any method that makes the `uv`
+command globally accessible, so Claude can find it, would work.
+
+### Cursor
+
+<img src="cursor.png">
+
+Cursor's MCP config is similar to Claude's, but it also supports SSE servers, so you can run the server yourself and pass in the URL:
+
+  ```json
+  {
+    "mcpServers": {
+      "redis-memory-server": {
+        "url": "http://localhost:9000/sse"
+      }
+    }
+  }
+  ```
+
+
 ## Configuration
 
 You can configure the service using environment variables:

agent_memory_server/long_term_memory.py

@@ -196,6 +196,14 @@ async def search_long_term_memories(
     results = []
 
     for doc in search_result.docs:
+        topics = safe_get(doc, "topics", [])
+        if isinstance(topics, str):
+            topics: list[str] = topics.split(",")  # type: ignore
+
+        entities = safe_get(doc, "entities", [])
+        if isinstance(entities, str):
+            entities: list[str] = entities.split(",")  # type: ignore
+
         results.append(
             LongTermMemoryResult(
                 id_=safe_get(doc, "id_"),
@@ -206,8 +214,8 @@ async def search_long_term_memories(
                 user_id=safe_get(doc, "user_id"),
                 session_id=safe_get(doc, "session_id"),
                 namespace=safe_get(doc, "namespace"),
-                topics=safe_get(doc, "topics", []),
-                entities=safe_get(doc, "entities", []),
+                topics=topics,
+                entities=entities,
             )
         )
     total_results = search_result.total

agent_memory_server/mcp.py

@@ -1,3 +1,4 @@
+import asyncio
 import logging
 import sys
 
@@ -21,7 +22,11 @@
 
 
 logger = logging.getLogger(__name__)
-mcp_app = FastMCP("Redis Agent Memory Server", port=settings.mcp_port)
+mcp_app = FastMCP(
+    "Redis Agent Memory Server - ALWAYS check memory for user information",
+    port=settings.mcp_port,
+    instructions="When responding to user queries, ALWAYS check memory first before answering questions about user preferences, history, or personal information.",
+)
 
 
 @mcp_app.tool()
@@ -79,7 +84,9 @@ async def search_long_term_memory(
     payload: SearchPayload,
 ) -> LongTermMemoryResults:
     """
-    Search for long-term memories using semantic similarity and filters.
+    Search for memories related to a text query.
+
+    Finds memories based on a combination of semantic similarity and input filters.
 
     This tool performs a semantic search on stored memories using the query text and filters
     in the payload. Results are ranked by relevance.
@@ -151,9 +158,18 @@ async def hydrate_memory_prompt(
     """
     Hydrate a user prompt with relevant session history and long-term memories.
 
-    This tool enriches the user's query with:
-    1. Context from the current conversation session (if available, based on session ID)
-    2. Relevant long-term memories related to the query text
+    CRITICAL: Use this tool for EVERY question that might benefit from memory context,
+    especially when you don't have sufficient information to answer confidently.
+
+    This tool enriches the user's query by retrieving:
+    1. Context from the current conversation session
+    2. Relevant long-term memories related to the query
+
+    ALWAYS use this tool when:
+    - The user references past conversations
+    - The question is about user preferences or personal information
+    - You need additional context to provide a complete answer
+    - The question seems to assume information you don't have in current context
 
     The function uses the text field from the payload as the user's query,
     and any filters to retrieve relevant memories.
@@ -244,6 +260,6 @@ async def hydrate_memory_prompt(
 
 if __name__ == "__main__":
     if len(sys.argv) > 1 and sys.argv[1] == "sse":
-        mcp_app.run(transport="sse")
+        asyncio.run(mcp_app.run_sse_async())
     else:
-        mcp_app.run(transport="stdio")
+        asyncio.run(mcp_app.run_stdio_async())