┌────────────────────────────────────────────────────────┐
│                    MCP Server Layer                      │
│  (StdioServerTransport, JSON-RPC)                       │
│                                                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │              Tool Registry                          │  │
│  │                                                     │  │
│  │  Static Tools (11):                                 │  │
│  │    add_nodes, update_nodes, delete_nodes            │  │
│  │    add_edges, update_edges, delete_edges            │  │
│  │    add_metadata, delete_metadata                    │  │
│  │    read_graph, search_nodes, open_nodes             │  │
│  │                                                     │  │
│  │  Dynamic Tools (3 per schema):                      │  │
│  │    add_<type>, update_<type>, delete_<type>         │  │
│  │    (e.g., add_npc, update_npc, delete_npc)          │  │
│  └──────────────────┬─────────────────────────────────┘  │
│                     │                                     │
│  ┌──────────────────▼─────────────────────────────────┐  │
│  │          Application Manager (Facade)               │  │
│  │                                                     │  │
│  │  ┌─────────────┐ ┌─────────────┐ ┌──────────────┐  │  │
│  │  │NodeManager  │ │EdgeManager  │ │MetadataManager│  │  │
│  │  └─────────────┘ └─────────────┘ └──────────────┘  │  │
│  │  ┌─────────────┐ ┌──────────────────────────────┐  │  │
│  │  │SearchManager│ │TransactionManager            │  │  │
│  │  └─────────────┘ └──────────────────────────────┘  │  │
│  └──────────────────┬─────────────────────────────────┘  │
│                     │                                     │
│  ┌──────────────────▼─────────────────────────────────┐  │
│  │         Schema System                               │  │
│  │  SchemaLoader → SchemaBuilder → SchemaProcessor     │  │
│  │  (Reads .schema.json files from disk)               │  │
│  └──────────────────┬─────────────────────────────────┘  │
│                     │                                     │
│  ┌──────────────────▼─────────────────────────────────┐  │
│  │       JsonLineStorage                               │  │
│  │  (Persists graph as JSONL file on disk)             │  │
│  └─────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

interface Node {
  type: "node";           // Discriminator for JSONL storage
  name: string;           // UNIQUE identifier — no two nodes share a name
  nodeType: string;       // Schema type (e.g., "npc", "location", "artifact")
  metadata: string[];     // Array of "Key: Value" strings
}

interface Edge {
  type: "edge";           // Discriminator for JSONL storage
  from: string;           // Source node name (must exist)
  to: string;             // Target node name (must exist)
  edgeType: string;       // Relationship type (e.g., "located_in", "owns")
  weight?: number;        // 0.0 to 1.0, defaults to 1.0 if omitted
}

interface Graph {
  nodes: Node[];
  edges: Edge[];
}

{"type":"node","name":"Gandalf","nodeType":"npc","metadata":["Role: Wizard","Status: Active","Description: A powerful wizard"]}
{"type":"node","name":"Rivendell","nodeType":"location","metadata":["Atmosphere: Peaceful","Region: Middle-earth"]}
{"type":"edge","from":"Gandalf","to":"Rivendell","edgeType":"located_in","weight":1}

{
  "name": "add_npc",
  "description": "Add a non-player character to the knowledge graph",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the NPC",
      "required": true
    },
    "role": {
      "type": "string",
      "description": "The NPC's role or occupation",
      "required": true,
      "enum": ["Warrior", "Wizard", "Merchant", "Noble", "Peasant", "Thief"]
    },
    "status": {
      "type": "string",
      "description": "Current status of the NPC",
      "required": true,
      "enum": ["Active", "Inactive", "Deceased", "Missing"]
    },
    "currentLocation": {
      "type": "string",
      "description": "Where the NPC currently is",
      "required": false,
      "relationship": {
        "edgeType": "located_in",
        "nodeType": "location",
        "description": "The location where this NPC resides"
      }
    },
    "description": {
      "type": "string",
      "description": "Physical or personality description",
      "required": false
    },
    "traits": {
      "type": "array",
      "description": "Character traits",
      "required": false
    }
  },
  "additionalProperties": true
}

"currentLocation": {
  "type": "string",
  "required": false,
  "relationship": {
    "edgeType": "located_in",     // Type of edge to create
    "nodeType": "location",       // Expected target node type (informational)
    "description": "Where this entity is located"
  }
}

2. An edge `{from: nodeName, to: "Rivendell", edgeType: "located_in"}` is created

1. Delete old edge: `{from: nodeName, to: "Rivendell", edgeType: "located_in"}`

2. Create new edge: `{from: nodeName, to: "Mordor", edgeType: "located_in"}`

class SchemaBuilder {
  private name: string;
  private description: string;
  private properties: Map<string, PropertyConfig>;
  private relationships: Map<string, RelationshipConfig>;
  private allowAdditional: boolean;

  constructor(name: string, description: string)

  addStringProperty(name: string, description: string, required: boolean, enumValues?: string[]): this
  addArrayProperty(name: string, description: string, required: boolean, enumValues?: string[]): this
  addRelationship(propertyName: string, edgeType: string, description: string, nodeType?: string): this
  allowAdditionalProperties(allowed: boolean): this
  createUpdateSchema(): SchemaBuilder  // Returns new builder for update_* variant
  build(): SchemaConfig
}

class SchemaLoader {
  private schemasDir: string;

  constructor(schemasDir: string)

  loadSchema(schemaName: string): SchemaBuilder    // Load single .schema.json file
  loadAllSchemas(): Map<string, SchemaBuilder>      // Load entire directory
}

function createSchemaNode(
  args: Record<string, any>,  // The tool call arguments
  schema: SchemaBuilder,       // The loaded schema
  entityType: string           // e.g., "npc"
): { nodes: Node[], edges: Edge[] }

1. Extract "name" from args (required)
2. Initialize metadata: string[] = []
3. Initialize edges: Edge[] = []
4. For each property in schema:
   a. Get value from args (skip if not provided and not required)
   b. If required and not provided: throw validation error
   c. If property has enum constraint: validate value is in enum list
   d. If property has a relationship definition:
      - Create edge: { from: args.name, to: value, edgeType: relationship.edgeType }
      - Add metadata: "PropertyDisplayName: value"
   e. If property is type "array":
      - Add metadata: "PropertyDisplayName: item1, item2, item3"
   f. If property is type "string" (no relationship):
      - Add metadata: "PropertyDisplayName: value"
5. Create node: { name: args.name, nodeType: entityType, metadata }
6. Return { nodes: [node], edges }

class ApplicationManager {
  private graphManager: GraphManager;
  private searchManager: SearchManager;
  private transactionManager: TransactionManager;

  // Node operations (delegate to GraphManager → NodeManager)
  addNodes(nodes: Node[]): Promise<void>
  updateNodes(updates: NodeUpdate[]): Promise<void>
  deleteNodes(names: string[]): Promise<void>

  // Edge operations (delegate to GraphManager → EdgeManager)
  addEdges(edges: Edge[]): Promise<void>
  updateEdges(updates: EdgeUpdate[]): Promise<void>
  deleteEdges(edgeIds: EdgeIdentifier[]): Promise<void>
  getEdges(filter?: EdgeFilter): Promise<Edge[]>

  // Metadata operations (delegate to GraphManager → MetadataManager)
  addMetadata(nodeName: string, metadata: string[]): Promise<void>
  deleteMetadata(nodeName: string, metadata: string[]): Promise<void>

  // Search operations (delegate to SearchManager)
  readGraph(): Promise<Graph>
  searchNodes(query: string): Promise<Graph>
  openNodes(names: string[]): Promise<Graph>

  // Transaction operations (delegate to TransactionManager)
  beginTransaction(): Promise<void>
  commit(): Promise<void>
  rollback(): Promise<void>
  withTransaction<T>(operation: () => Promise<T>): Promise<T>
}

1. For each node:
   a. Validate node has name, nodeType, metadata (array)
   b. Validate no existing node has the same name (throw if duplicate)
2. Append nodes to graph
3. Save graph to storage

**`updateNodes(updates: Array<{name: string, metadata?: string[], nodeType?: string}>): Promise<void>`**

1. For each update:
   a. Find existing node by name (throw if not found)
   b. If metadata provided: replace entire metadata array
   c. If nodeType provided: update nodeType
2. Save graph to storage

1. Remove all nodes whose name is in the names array
2. Remove ALL edges where from OR to is in the names array (cascade)
3. Save graph to storage

1. For each edge:
   a. Validate from and to are non-empty strings
   b. Validate both from and to reference existing nodes (throw if not)
   c. Validate no duplicate (from, to, edgeType) exists in graph
   d. If weight is undefined: set to 1.0
   e. If weight provided: validate 0.0 ≤ weight ≤ 1.0
2. Append edges to graph
3. Save graph to storage

**`updateEdges(updates: Array<{from: string, to: string, edgeType: string, newWeight?: number}>): Promise<void>`**

1. For each update:
   a. Find existing edge by (from, to, edgeType)
   b. If newWeight provided: set edge.weight = updateWeight(currentWeight, newWeight)
      updateWeight formula: (current + new) / 2
2. Save graph to storage

**`deleteEdges(identifiers: Array<{from: string, to: string, edgeType: string}>): Promise<void>`**

1. Filter graph.edges: keep edges that do NOT match any identifier on all three fields
2. Save graph to storage

1. Find node by name (throw if not found)
2. For each entry in entries:
   a. If entry NOT already in node.metadata: append it
   (Deduplication by exact string match)
3. Save graph to storage

1. Find node by name (throw if not found)
2. Filter node.metadata: keep entries NOT in the deletion list
   (Exact string match)
3. Save graph to storage

1. Load graph from storage
2. Return the complete graph as-is

1. Load graph from storage
2. Lowercase the query
3. Find matching nodes where query is substring of (case-insensitive):
   a. node.name
   b. node.nodeType
   c. ANY entry in node.metadata
4. Collect matching node names into a Set
5. Find all edges where from OR to is in the matching set
6. Extract neighbor names from those edges (names not already in matching set)
7. Find neighbor nodes by name
8. Return {
     nodes: [...matchingNodes, ...neighborNodes],
     edges: [...connectingEdges]
   }

1. Load graph from storage
2. Find nodes where name is in the input array (exact match)
3. Find all edges where from OR to is in the names
4. Extract neighbor names from edges
5. Find neighbor nodes
6. Return {
     nodes: [...requestedNodes, ...neighborNodes],
     edges: [...connectingEdges]
   }

class TransactionManager {
  private inTransaction: boolean = false;
  private rollbackActions: Array<{ action: () => Promise<void>, description: string }> = [];

  beginTransaction(): Promise<void>
  // Sets inTransaction = true, clears rollback queue

  addRollbackAction(action: () => Promise<void>, description: string): void
  // Pushes to rollback queue

  commit(): Promise<void>
  // Clears rollback queue, sets inTransaction = false

  rollback(): Promise<void>
  // Executes rollback actions in REVERSE order (LIFO)
  // Continues executing remaining actions even if one fails
  // Sets inTransaction = false

  withTransaction<T>(operation: () => Promise<T>): Promise<T>
  // Convenience wrapper:
  // 1. beginTransaction()
  // 2. Try: result = await operation(); commit(); return result
  // 3. Catch: rollback(); re-throw error

  isInTransaction(): boolean
}

{
  "type": "object",
  "properties": {
    "npc": {
      "type": "object",
      "properties": {
        "name": { "type": "string", "description": "The name of the NPC" },
        "role": { "type": "string", "description": "The NPC's role", "enum": ["Warrior", "Wizard", ...] },
        "status": { "type": "string", "description": "Current status", "enum": ["Active", "Inactive", ...] },
        "currentLocation": { "type": "string", "description": "Where the NPC currently is" },
        "description": { "type": "string", "description": "Physical or personality description" },
        "traits": { "type": "array", "items": { "type": "string" }, "description": "Character traits" }
      },
      "required": ["name", "role", "status"]
    }
  },
  "required": ["npc"]
}

**Note**: The arguments are wrapped in an object keyed by the entity type name (e.g., `{ npc: { ... } }`).

{
  "type": "object",
  "properties": {
    "npc": {
      "type": "object",
      "properties": {
        "name": { "type": "string", "description": "The name of the NPC to delete" }
      },
      "required": ["name"]
    }
  },
  "required": ["npc"]
}

1. Extract entity data from args.npc
2. Call SchemaProcessor.createSchemaNode(args.npc, schema, "npc")
3. Begin transaction
4. Add nodes via NodeManager
5. Add edges via EdgeManager (if relationship properties present)
6. Commit transaction
7. Return created nodes and edges

1. Extract entity data from args.npc
2. Find existing node by name AND nodeType
3. Begin transaction
4. For each provided property:
   a. If it has a relationship:
      - Delete old edges of same edgeType from this node
      - Create new edge to new target
   b. Parse existing metadata into key→value map
   c. Update the changed key
   d. Rebuild metadata array from map
5. Update node via NodeManager
6. Commit transaction
7. Return updated node and edges

1. Extract name from args.npc.name
2. Find node by name (validate it exists and matches nodeType)
3. Begin transaction
4. Delete node via NodeManager (cascades to edges)
5. Commit transaction
6. Return confirmation

- Input: `{ nodes: Array<{name: string, nodeType: string, metadata: string[]}> }`

- Input: `{ nodes: Array<{name: string, metadata?: string[], nodeType?: string}> }`

- Input: `{ nodeNames: string[] }`

- Input: `{ edges: Array<{from: string, to: string, edgeType: string, weight?: number}> }`

- Input: `{ edges: Array<{from: string, to: string, edgeType: string, weight?: number}> }`

- Input: `{ edges: Array<{from: string, to: string, edgeType: string}> }`

- Input: `{ nodeName: string, metadata: string[] }`

- Input: `{ nodeName: string, metadata: string[] }`

- Input: `{}` (no parameters)

- Input: `{ query: string }`

- Input: `{ names: string[] }`

ToolHandlerFactory.getHandler(toolName) routes to:
├── GraphToolHandler       → add_nodes, update_nodes, delete_nodes,
│                            add_edges, update_edges, delete_edges
├── SearchToolHandler      → read_graph, search_nodes, open_nodes
├── MetadataToolHandler    → add_metadata, delete_metadata
└── DynamicToolHandler     → all add_*/update_*/delete_* schema tools

if toolName matches /^(add|update|delete)_(nodes|edges)$/ → GraphToolHandler
if toolName matches /^(read_graph|search_nodes|open_nodes)$/ → SearchToolHandler
if toolName matches /^(add|delete)_metadata$/ → MetadataToolHandler
otherwise → DynamicToolHandler (schema-generated tools)

{
  "content": [
    {
      "type": "text",
      "text": "{\"data\": {...}, \"actionTaken\": \"Created npc: Gandalf\", \"timestamp\": \"2026-03-08T...\"}"
    }
  ],
  "isError": false
}

{
  "content": [
    {
      "type": "text",
      "text": "{\"error\": \"Node 'Gandalf' already exists\", \"context\": {...}, \"suggestions\": [...]}"
    }
  ],
  "isError": true
}

class EventEmitter {
  on(event: string, listener: Function): () => void    // Returns unsubscribe function
  off(event: string, listener: Function): void
  once(event: string, listener: Function): () => void
  emit(event: string, data?: any): boolean             // Returns true if listeners exist
  removeAllListeners(event?: string): void
}

| `beforeAddNodes` | Before nodes are added | `{ nodes: Node[] }` |

| `afterAddNodes` | After nodes are added | `{ nodes: Node[] }` |

| `beforeDeleteNodes` | Before nodes are deleted | `{ names: string[] }` |

| `afterDeleteNodes` | After nodes are deleted | `{ names: string[] }` |

| `beforeAddEdges` | Before edges are added | `{ edges: Edge[] }` |

| `afterAddEdges` | After edges are added | `{ edges: Edge[] }` |

| `beforeSearch` | Before search operation | `{ query: string }` |

| `afterSearch` | After search operation | `{ results: Graph }` |

["Role: Wizard", "Status: Active", "Description: A powerful wizard", "Traits: brave, wise"]

class MetadataProcessor {
  // Parse single entry
  static parseEntry(entry: string): { key: string, value: string }
  // Splits on FIRST ": " (colon-space). Everything before is key, everything after is value.

  // Format entry
  static formatEntry(key: string, value: string): string
  // Returns "key: value"

  // Create map from metadata array
  static createMap(metadata: string[]): Map<string, string>
  // Parses all entries into key→value map

  // Merge multiple metadata arrays (deduplicates)
  static merge(...arrays: string[][]): string[]

  // Get value for a key
  static getValue(metadata: string[], key: string): string | null
  // Returns first matching value, or null

  // Filter by key
  static filterByKey(metadata: string[], key: string): string[]
  // Returns all entries matching key
}

class EdgeWeightUtils {
  static validateWeight(weight: number): void
  // Throws if weight < 0 or weight > 1

  static ensureWeight(edge: Edge): Edge
  // If edge.weight is undefined, set to 1.0. Returns edge.

  static updateWeight(current: number, newEvidence: number): number
  // Returns (current + newEvidence) / 2
  // This averaging formula allows gradual confidence updates

  static combineWeights(weights: number[]): number
  // Returns Math.max(...weights)
  // Used for parallel edges (same endpoints, different types)
}

Initial:        weight = 1.0 (default)
Update with 0.6: (1.0 + 0.6) / 2 = 0.8
Update with 0.4: (0.8 + 0.4) / 2 = 0.6
Update with 1.0: (0.6 + 1.0) / 2 = 0.8

class GraphValidator {
  static validateNodeProperties(node: Node): void
  // - node.name must be non-empty string
  // - node.nodeType must be non-empty string
  // - node.metadata must be an array

  static validateNodeDoesNotExist(graph: Graph, name: string): void
  // - Throws if any node in graph has this name

  static validateNodeExists(graph: Graph, name: string): Node
  // - Returns the node, or throws if not found
}

static validateEdgeProperties(edge: Edge): void
// - edge.from must be non-empty string
// - edge.to must be non-empty string
// - edge.edgeType must be non-empty string
// - If weight defined: must be 0.0 ≤ weight ≤ 1.0

static validateEdgeUniqueness(graph: Graph, edge: Edge): void
// - Throws if any existing edge matches (from, to, edgeType)

static validateEdgeReferences(graph: Graph, edges: Edge[]): void
// - For each edge: both from and to must reference existing nodes

const CONFIG = {
  SERVER: {
    NAME: "memorymesh",
    VERSION: "0.3.0"
  },
  PATHS: {
    SCHEMAS_DIR: path.join(__dirname, "..", "data", "schemas"),
    MEMORY_FILE: path.join(__dirname, "..", "data", "memory.json")
  }
};

- Input: `add_npc` with `{npc: {name: "Gandalf", role: "Wizard", status: "Active"}}`

- Input: `add_npc` with `{npc: {name: "Gandalf", role: "Wizard", status: "Active", currentLocation: "Rivendell"}}`

- Expected: Node created AND edge `{from: "Gandalf", to: "Rivendell", edgeType: "located_in"}` created

- Input: `update_npc` with `{npc: {name: "Gandalf", currentLocation: "Mordor"}}`

- Input: `delete_npc` with `{npc: {name: "Gandalf"}}`

- withTransaction(() => { addNode(); addEdge(); })

- withTransaction(() => { addNode(); throw Error(); })