┌─────────────────────────────────────────────────┐
│                  MCP Server                      │
│  (StdioServerTransport — communicates via stdin/ │
│   stdout using JSON-RPC over MCP protocol)       │
│                                                  │
│  ┌─────────────────────────────────────────────┐ │
│  │          9 Registered MCP Tools             │ │
│  │  create_entities, create_relations,         │ │
│  │  add_observations, delete_entities,         │ │
│  │  delete_observations, delete_relations,     │ │
│  │  read_graph, search_nodes, open_nodes       │ │
│  └──────────────────┬──────────────────────────┘ │
│                     │                            │
│  ┌──────────────────▼──────────────────────────┐ │
│  │       KnowledgeGraphManager Class           │ │
│  │                                             │ │
│  │  In-memory state:                           │ │
│  │    KnowledgeGraph {                         │ │
│  │      entities: Entity[]                     │ │
│  │      relations: Relation[]                  │ │
│  │    }                                        │ │
│  │                                             │ │
│  │  Methods:                                   │ │
│  │    loadGraph() → read entire JSONL file     │ │
│  │    saveGraph() → write entire JSONL file    │ │
│  │    createEntities(entities)                 │ │
│  │    createRelations(relations)               │ │
│  │    addObservations(observations)            │ │
│  │    deleteEntities(entityNames)              │ │
│  │    deleteObservations(deletions)            │ │
│  │    deleteRelations(relations)               │ │
│  │    searchNodes(query)                       │ │
│  │    openNodes(names)                         │ │
│  │    readGraph()                              │ │
│  └──────────────────┬──────────────────────────┘ │
│                     │                            │
│  ┌──────────────────▼──────────────────────────┐ │
│  │         JSONL File on Disk                  │ │
│  │   (default: memory.jsonl in CWD)            │ │
│  │   Each line: one JSON object                │ │
│  │   Entity lines + Relation lines             │ │
│  └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

interface Entity {
  name: string;          // Unique identifier (e.g., "John_Smith")
  entityType: string;    // Category (e.g., "person", "organization", "concept")
  observations: string[]; // Array of factual strings about this entity
}

interface Relation {
  from: string;       // Source entity name (must reference existing entity)
  to: string;         // Target entity name (must reference existing entity)
  relationType: string; // Describes the relationship (e.g., "works_at", "knows")
}

interface KnowledgeGraph {
  entities: Entity[];
  relations: Relation[];
}

{"type":"entity","name":"John_Smith","entityType":"person","observations":["Is 30 years old","Works at Acme Corp","Likes hiking"]}

{"type":"relation","from":"John_Smith","to":"Acme_Corp","relationType":"works_at"}

{"type":"entity","name":"John_Smith","entityType":"person","observations":["Is 30 years old","Lives in Portland"]}
{"type":"entity","name":"Acme_Corp","entityType":"organization","observations":["Founded in 2010","Has 500 employees"]}
{"type":"relation","from":"John_Smith","to":"Acme_Corp","relationType":"works_at"}
{"type":"relation","from":"John_Smith","to":"Acme_Corp","relationType":"knows_about"}

6. If the file doesn't exist, return `{ entities: [], relations: [] }`

1. Map each entity to JSON string with `type: "entity"` prepended: `JSON.stringify({ type: "entity", ...entity })`

2. Map each relation to JSON string with `type: "relation"` prepended: `JSON.stringify({ type: "relation", ...relation })`

class KnowledgeGraphManager {
  private memoryFilePath: string;

  constructor(memoryFilePath: string) {
    this.memoryFilePath = memoryFilePath;
  }
}

1. Try to read file at this.memoryFilePath as UTF-8 string
2. If file does not exist (ENOENT error), return { entities: [], relations: [] }
3. Split the string by "\n"
4. Filter out empty strings (handles trailing newline)
5. Parse each remaining string as JSON
6. Reduce the parsed objects into { entities: [], relations: [] }:
   For each item:
     - If item.type === "entity":
       Create new object WITHOUT the "type" field: { name, entityType, observations }
       Push to entities array
     - If item.type === "relation":
       Create new object WITHOUT the "type" field: { from, to, relationType }
       Push to relations array
7. Return the KnowledgeGraph

**Key detail**: The `type` field is destructured out and discarded. Use object rest/spread: `const { type, ...rest } = item` then push `rest`.

1. Map each entity to: JSON.stringify({ type: "entity", ...entity })
2. Map each relation to: JSON.stringify({ type: "relation", ...relation })
3. Concatenate: [...entityLines, ...relationLines].join("\n")
4. Write to this.memoryFilePath (overwrites entire file)

1. Load the full graph from disk
2. Filter the input entities: keep only those where NO existing entity has the same name
   - Comparison: exact string match on entity.name (case-SENSITIVE)
3. Append the filtered new entities to graph.entities
4. Save the full graph to disk
5. Return ONLY the newly created entities (the filtered list, not the full graph)

1. Load the full graph from disk
2. Filter the input relations: keep only those where NO existing relation matches ALL THREE fields:
   - relation.from === existing.from  (exact match)
   - relation.to === existing.to      (exact match)
   - relation.relationType === existing.relationType (exact match)
3. Append the filtered new relations to graph.relations
4. Save the full graph to disk
5. Return ONLY the newly created relations

### 3.6 `addObservations(observations: Array<{entityName: string, contents: string[]}>): Promise<Array<{entityName: string, addedObservations: string[]}>>`

1. Load the full graph from disk
2. For each item in the observations array:
   a. Find the entity where entity.name === item.entityName
   b. If NOT found: throw an Error with message "Entity with name {entityName} not found"
   c. Filter item.contents: keep only strings NOT already in entity.observations
      - Comparison: exact string match (case-SENSITIVE)
   d. Append the filtered new observations to entity.observations
   e. Record { entityName: item.entityName, addedObservations: [the filtered new ones] }
3. Save the full graph to disk
4. Return the array of { entityName, addedObservations } records

1. Load the full graph from disk
2. Filter graph.entities: keep entities whose name is NOT in the entityNames array
3. Filter graph.relations: keep relations where NEITHER from NOR to is in the entityNames array
   - A relation is removed if relation.from is in entityNames OR relation.to is in entityNames
4. Save the full graph to disk

### 3.8 `deleteObservations(deletions: Array<{entityName: string, observations: string[]}>): Promise<void>`

1. Load the full graph from disk
2. For each deletion item:
   a. Find the entity where entity.name === item.entityName
   b. If entity is found:
      Filter entity.observations: keep only those NOT in item.observations
   c. If entity is NOT found: silently skip (no error thrown)
3. Save the full graph to disk

1. Load the full graph from disk
2. Filter graph.relations: keep relations where NO item in the input array matches ALL THREE:
   - relation.from === item.from
   - relation.to === item.to
   - relation.relationType === item.relationType
3. Save the full graph to disk

1. Load the full graph from disk
2. Return it as-is

1. Load the full graph from disk
2. Lowercase the query string
3. Filter entities where ANY of the following contains the lowercased query as a substring:
   a. entity.name.toLowerCase()
   b. entity.entityType.toLowerCase()
   c. ANY string in entity.observations where observation.toLowerCase() contains the query
4. Collect the names of all matching entities into a Set
5. Filter relations where:
   relation.from is in the matching names Set OR relation.to is in the matching names Set
   (At least ONE endpoint must be a matching entity)
6. Return { entities: [matching entities], relations: [matching relations] }

1. Load the full graph from disk
2. Filter entities where entity.name is in the names array (exact match, case-SENSITIVE)
3. Collect the matched entity names into a Set
4. Filter relations where:
   relation.from is in the matched names Set OR relation.to is in the matched names Set
   (At least ONE endpoint must be in the requested names)
5. Return { entities: [matched entities], relations: [connected relations] }

{
  entities: Array<{
    name: string,        // The name of the entity
    entityType: string,  // The type of the entity
    observations: string[] // An array of observation contents
  }>
}

{
  relations: Array<{
    from: string,         // The name of the entity the relation starts from
    to: string,           // The name of the entity the relation points to
    relationType: string  // The type of the relation
  }>
}

{
  observations: Array<{
    entityName: string,  // The name of the entity to add observations to
    contents: string[]   // An array of observation strings to add
  }>
}

{
  entityNames: string[]  // An array of entity names to delete
}

{
  deletions: Array<{
    entityName: string,    // The name of the entity
    observations: string[] // The observations to delete
  }>
}

{
  relations: Array<{
    from: string,
    to: string,
    relationType: string
  }>
}

**Input Schema:** `{}` (empty object — no parameters)

{
  query: string  // The search query string
}

{
  names: string[]  // An array of entity names to retrieve
}

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";  // Note: zod is a transitive dependency of the MCP SDK

const server = new McpServer({
  name: "memory",
  version: "1.0.0",
});

server.tool(
  toolName: string,
  description: string,
  inputSchema: Record<string, ZodType>,  // Zod schemas for each parameter
  handler: async (args) => { content: [{ type: "text", text: string }] }
);

server.tool(
  "create_entities",
  "Create multiple new entities in the knowledge graph",
  {
    entities: z.array(z.object({
      name: z.string().describe("The name of the entity"),
      entityType: z.string().describe("The type of the entity"),
      observations: z.array(z.string()).describe("An array of observation contents"),
    })).describe("Array of entities to create"),
  },
  async ({ entities }) => {
    const result = await manager.createEntities(entities);
    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

1. Check for MEMORY_FILE_PATH environment variable
2. If set and is an absolute path: use it as-is
3. If set and is a relative path: resolve it relative to the current working directory
4. If not set: use "memory.jsonl" in the current working directory
5. Run legacy migration check (see 6.2)
6. Return the resolved path

1. If the resolved JSONL file already exists: return (no migration needed)
2. Derive the legacy path: replace the .jsonl extension with .json
   (e.g., "/path/to/memory.jsonl" → "/path/to/memory.json")
3. If the legacy .json file exists:
   a. Read its contents
   b. Write the same contents to the new .jsonl path
   c. Delete the old .json file
4. If neither file exists: do nothing (fresh start)

{
  "name": "@modelcontextprotocol/server-memory",
  "version": "0.6.3",
  "type": "module",
  "bin": {
    "mcp-server-memory": "dist/index.js"
  },
  "files": ["dist"],
  "scripts": {
    "build": "tsc && node -e \"require('fs').chmodSync('dist/index.js', '755')\"",
    "watch": "tsc --watch"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.26.0"
  }
}

#!/usr/bin/env node

- Input: Create entities `[{name: "Alice", entityType: "person", observations: ["Is a student"]}]`

- Input: Create relation `{from: "Alice", to: "Bob", relationType: "knows"}`

- Setup: Create relation `{from: "Alice", to: "Bob", relationType: "knows"}`

- Setup: Create relation `{from: "Alice", to: "Bob", relationType: "knows"}`

- Input: Create relation `{from: "Alice", to: "Bob", relationType: "likes"}`

- Setup: Create relation `{from: "Alice", to: "Bob", relationType: "knows"}`

- Input: Create relation `{from: "Bob", to: "Alice", relationType: "knows"}`

- Expected: Returns `[{entityName: "Alice", addedObservations: ["Likes pizza"]}]`

- Expected: Returns `[{entityName: "Alice", addedObservations: ["Likes pizza"]}]`

- Input: Delete relations `[{from: "A", to: "B", relationType: "knows"}]`

- Expected: Returns `{ entities: [], relations: [] }`

- Expected path: `{cwd}/memory.jsonl`

- Expected path: `{cwd}/data/graph.jsonl`

Follow these steps for each interaction:

1. Memory Retrieval:
   - Always begin by using search_nodes or open_nodes to retrieve relevant information
   - Use read_graph for a comprehensive view when needed

2. Memory Storage:
   - After each interaction, identify key facts, preferences, and relationships
   - Create entities for people, organizations, concepts, events
   - Create relations between entities
   - Add observations for specific facts and details
   - Update existing observations when information changes

3. Memory Maintenance:
   - Use delete operations to remove outdated or incorrect information
   - Consolidate related observations when entities grow large

A fresh install with no file on disk returns `{ entities: [], relations: [] }` for all read operations. All create operations work normally from an empty state.