Merge pull request #19 from modelcontextprotocol/memory_mcp_improvements

Memory mcp README improvements

src/memory/README.md

@@ -1,11 +1,9 @@
 # Knowledge Graph Memory Server
-A basic MCP server implementation that provides persistent memory using a knowledge-graph. The server manages entities, their observations, and the relationships between them using a JSON-based file system.
+A basic implementation of persistent memory using a local knowledge graph. This lets Claude remember information about the user across chats.
 
-This lets Claude remember information about the user across chats and projects, and lets them bypass the issues of having super long chats
+## Core Concepts
 
-# Core Concepts
-
-## Entities
+### Entities
 Entities are the primary nodes in the knowledge graph. Each entity has:
 - A unique name (identifier)
 - An entity type (e.g., "person", "organization", "event")
@@ -16,20 +14,22 @@ Example:
 {
   "name": "John_Smith",
   "entityType": "person",
-  "observations": ["Lives in New York", "Works as a software engineer"]
+  "observations": ["Speaks fluent Spanish"]
 }
 ```
 
-## Relations
+### Relations
 Relations define directed connections between entities. They are always stored in active voice and describe how entities interact or relate to each other.
+
 Example:
-```jsonCopy{
+```json
+{
   "from": "John_Smith",
-  "to": "TechCorp",
+  "to": "Anthropic",
   "relationType": "works_at"
 }
 ```
-## Observations
+### Observations
 Observations are discrete pieces of information about an entity. They are:
 
 - Stored as strings
@@ -38,7 +38,8 @@ Observations are discrete pieces of information about an entity. They are:
 - Should be atomic (one fact per observation)
 
 Example:
-```jsonCopy{
+```json
+{
   "entityName": "John_Smith",
   "observations": [
     "Speaks fluent Spanish",
@@ -48,31 +49,98 @@ Example:
 }
 ```
 
-# Tools
-
-## Entity Management
-
-- create_entities: Create new entities in the knowledge graph with names, types, and observations
-- delete_entities: Remove entities and their associated relations from the graph
-- add_observations: Add new observations to existing entities
-- delete_observations: Remove specific observations from entities
-
-
-## Relation Management
-
-- create_relations: Establish relationships between entities in active voice
-- delete_relations: Remove specific relationships between entities
-
-
-## Query Tools
+## API
+
+### Tools
+- **create_entities**
+  - Create multiple new entities in the knowledge graph
+  - Input: `entities` (array of objects)
+    - Each object contains:
+      - `name` (string): Entity identifier
+      - `entityType` (string): Type classification
+      - `observations` (string[]): Associated observations
+  - Ignores entities with existing names
+
+- **create_relations**
+  - Create multiple new relations between entities
+  - Input: `relations` (array of objects)
+    - Each object contains:
+      - `from` (string): Source entity name
+      - `to` (string): Target entity name
+      - `relationType` (string): Relationship type in active voice
+  - Skips duplicate relations
+
+- **add_observations**
+  - Add new observations to existing entities
+  - Input: `observations` (array of objects)
+    - Each object contains:
+      - `entityName` (string): Target entity
+      - `contents` (string[]): New observations to add
+  - Returns added observations per entity
+  - Fails if entity doesn't exist
+
+- **delete_entities**
+  - Remove entities and their relations
+  - Input: `entityNames` (string[])
+  - Cascading deletion of associated relations
+  - Silent operation if entity doesn't exist
+
+- **delete_observations**
+  - Remove specific observations from entities
+  - Input: `deletions` (array of objects)
+    - Each object contains:
+      - `entityName` (string): Target entity
+      - `observations` (string[]): Observations to remove
+  - Silent operation if observation doesn't exist
+
+- **delete_relations**
+  - Remove specific relations from the graph
+  - Input: `relations` (array of objects)
+    - Each object contains:
+      - `from` (string): Source entity name
+      - `to` (string): Target entity name
+      - `relationType` (string): Relationship type
+  - Silent operation if relation doesn't exist
+
+- **read_graph**
+  - Read the entire knowledge graph
+  - No input required
+  - Returns complete graph structure with all entities and relations
+
+- **search_nodes**
+  - Search for nodes based on query
+  - Input: `query` (string)
+  - Searches across:
+    - Entity names
+    - Entity types
+    - Observation content
+  - Returns matching entities and their relations
+
+- **open_nodes**
+  - Retrieve specific nodes by name
+  - Input: `names` (string[])
+  - Returns:
+    - Requested entities
+    - Relations between requested entities
+  - Silently skips non-existent nodes
+
+# Usage with Claude Desktop
+
+### Setup
+Add this to your claude_desktop_config.json:
+```json
+{
+  "mcp-server-memory": {
+    "command": "mcp-server-memory"
+  }
+}
+```
 
-- read_graph: Retrieve the entire knowledge graph
-- search_nodes: Search for nodes based on names, types, and observation content
-- open_nodes: Access specific nodes by their names
+### System Prompt
 
-# Prompts
+The prompt for utilizing memory depends on the use case. Changing the prompt will help the model determine the frequency and types of memories created.
 
-The prompt for utilizing memory depends on the use case, but here is an example prompt for chat personalization. You could use this prompt in the "Custom Instructions" field of a Project
+Here is an example prompt for chat personalization. You could use this prompt in the "Custom Instructions" field of a [Claude.ai Project](https://www.anthropic.com/news/projects). 
 
 ```
 Follow these steps for each interaction:
@@ -83,19 +151,19 @@ Follow these steps for each interaction:
 
 2. Memory Retrieval:
    - Always begin your chat by saying only "Remembering..." and retrieve all relevant information from your knowledge graph
-   - Always refer to your knowledge as your "memory"
+   - Always refer to your knowledge graph as your "memory"
 
 3. Memory
    - While conversing with the user, be attentive to any new information that falls into these categories:
-     a) Basic Identity (Age, gender, location, Job title, education level, etc.)
+     a) Basic Identity (age, gender, location, job title, education level, etc.)
      b) Behaviors (interests, habits, etc.)
      c) Preferences (communication style, preferred language, etc.)
-     d) Goals/Psychology (Goals, targets, aspirations, etc.)
+     d) Goals (goals, targets, aspirations, etc.)
      e) Relationships (personal and professional relationships up to 3 degrees of separation)
 
 4. Memory Update:
    - If any new information was gathered during the interaction, update your memory as follows:
-     a) Create nodes for recurring organizations, people, and significant events, connecting them to the current node.
-     b) Store most facts as observations within these nodes
-   - Try to perform all updates in one operation using the create and delete functions.
+     a) Create entities for recurring organizations, people, and significant events
+     b) Connect them to the current entities using relations
+     b) Store facts about them as observations
 ```