Skip to main content
Glama
MCP Notes

MCP Notes

by HefnySco

🧠 MCP Notes

MCP Notes is a powerful memory server that helps AI assistants remember and connect information over time. Think of it as a smart knowledge graph where you can store facts about people, projects, or concepts, link them together, and retrieve them intelligentlyβ€”perfect for building AI agents with long-term memory.

Whether you're tracking user preferences, maintaining project context, or building relationship maps, MCP Notes provides a structured way to persist, search, and traverse your knowledge graph with confidence scores, timestamps, and rich metadata.

✨ Features

  • πŸ—οΈ Entity Management - Create, read, search, and delete entities with types and observations

  • πŸ“ Observation Tracking - Add and remove observations with timestamps, confidence scores, and sources

  • πŸ”— Relation Management - Create and delete relations between entities to build connections

  • πŸ” Knowledge Graph Operations - Read the entire graph, search for specific nodes, or traverse connected entities

  • ⏰ Temporal Queries - Query entities by time range using createdAt/updatedAt timestamps

  • 🚢 Graph Traversal - Walk relations to find connected entities (multi-hop BFS)

  • πŸ“Š Rich Metadata - Support for optional metadata, confidence scores, and source tracking

  • πŸ”„ Auto-Migration - Automatically migrates legacy plain-string observations to rich format on load

  • πŸ’Ύ Persistent Storage - JSON file storage with daily logging for reliability

Related MCP server: KGrag MCP Server

πŸš€ Installation

# Clone the repository
git clone <your-repo-url>
cd mcp_notes

# Install dependencies
npm install

# Build the TypeScript code
npm run build

🎯 Quick Start

Running the Server

npm start

The server runs on stdio and connects to any MCP-compatible client.

Basic Example

{
  "entities": [
    {
      "name": "Alice",
      "entityType": "person",
      "observations": [
        "Alice is a software engineer",
        {
          "content": "Alice lives in San Francisco",
          "confidence": 0.9,
          "source": "user_profile"
        }
      ]
    }
  ]
}

Create relations between entities:

{
  "relations": [
    {
      "from": "Alice",
      "to": "Bob",
      "relationType": "works with"
    }
  ]
}

πŸ› οΈ Available Tools

create_entities

Create multiple new entities in the knowledge graph.

Parameters:

  • entities (array): Array of entity objects with:

    • name (string): The name of the entity

    • entityType (string): The type of the entity

    • observations (array): Initial observations (can be strings or objects with content, confidence, source)

    • metadata (object, optional): Additional metadata for the entity

add_observations

Add new observations to existing entities.

Parameters:

  • observations (array): Array of observation additions with:

    • entityName (string): Name of the entity

    • contents (array): Observations to add (can be strings or objects with content, confidence, source)

create_relations

Create relations between entities.

Parameters:

  • relations (array): Array of relation objects with:

    • from (string): Source entity name

    • to (string): Target entity name

    • relationType (string): Type of relation (use active voice)

delete_entities

Delete entities and their associated relations.

Parameters:

  • entityNames (array of strings): Names of entities to delete

delete_observations

Delete specific observations from entities.

Parameters:

  • deletions (array): Array of deletion objects with:

    • entityName (string): Name of the entity

    • observations (array of strings): Observations to delete

delete_relations

Delete relations from the knowledge graph.

Parameters:

  • relations (array): Array of relation objects to delete

open_nodes

Retrieve specific entities by name.

Parameters:

  • names (array of strings): Entity names to retrieve

read_graph

Read the entire knowledge graph including all entities and relations.

search_nodes

Search for entities matching a query.

Parameters:

  • query (string): Search query (matches entity names, types, and observation content)

query_by_time

Query entities and observations by time range using createdAt/updatedAt timestamps.

Parameters:

  • since (string, optional): ISO timestamp for start of time range (inclusive)

  • until (string, optional): ISO timestamp for end of time range (inclusive)

  • limit (number, optional): Maximum number of results to return

  • sort (string, optional): Sort order by updatedAt - "asc" or "desc" (default: "desc")

get_recent

Get the most recently updated entities.

Parameters:

  • limit (number, optional): Maximum number of recent entities to return (default: 10)

traverse_graph

Traverse the knowledge graph from a starting entity to find connected entities via relations.

Parameters:

  • start (string, required): Name of the entity to start traversal from

  • depth (number, optional): Number of hops to traverse (default: 1)

  • direction (string, optional): Direction of traversal - "out" (outgoing relations), "in" (incoming relations), or "both" (default: "both")

πŸ› οΈ Development

# Build
npm run build

# Watch mode for development
npm run dev

Type Definitions

TypeScript types are defined in src/types.ts for:

  • Entity (with createdAt, updatedAt, metadata)

  • Observation (with content, createdAt, confidence, source)

  • Relation

  • ObservationAddition

  • ObservationDeletion

  • RelationDeletion

  • KnowledgeGraph

  • GraphTraversalResult

πŸ“Š Data Model

Observations

Observations are rich objects with metadata:

interface Observation {
  content: string;
  createdAt: string; // ISO timestamp
  confidence?: number; // 0-1
  source?: string;
}

Entities

Entities include timestamps and optional metadata:

interface Entity {
  name: string;
  entityType: string;
  observations: Observation[];
  createdAt: string; // ISO timestamp
  updatedAt: string; // ISO timestamp
  metadata?: Record<string, unknown>;
}

Auto-Migration

Legacy data with plain-string observations is automatically migrated on load. Plain strings are converted to Observation objects with createdAt set to the current time.

βš™οΈ Configuration

Add this server to your MCP client configuration:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/mcp_notes/dist/index.js"]
    }
  }
}

πŸ“ Architecture

  • src/index.ts - Main MCP server with tool handlers

  • src/memoryService.ts - Core memory service managing the knowledge graph

  • src/types.ts - TypeScript type definitions

πŸ“„ License

MIT

Available Tools

13 tools
add_observationsC

Add new observations to existing entities in the knowledge graph

Inputs: observations (required).

create_entitiesC

Create multiple new entities in the knowledge graph

Inputs: entities (required).

create_relationsB

Create multiple new relations between entities in the knowledge graph. Relations should be in active voice

Inputs: relations (required).

delete_entitiesA

Delete multiple entities and their associated relations from the knowledge graph

Inputs: entityNames (required).

delete_observationsB

Delete specific observations from entities in the knowledge graph

Inputs: deletions (required).

delete_relationsA

Delete multiple relations from the knowledge graph

Inputs: relations (required).

get_recentC

Get the most recently updated entities

Inputs: limit.

get_versionA

Get the version information of this memory MCP server

Inputs: no named parameters.

open_nodesC

Open specific nodes in the knowledge graph by their names

Inputs: names (required).

query_by_timeB

Query entities and observations by time range using createdAt/updatedAt timestamps

Inputs: since, until, limit, sort.

read_graphB

Read the entire knowledge graph

Inputs: no named parameters.

search_nodesC

Search for nodes in the knowledge graph based on a query

Inputs: query (required).

traverse_graphB

Traverse the knowledge graph from a starting entity to find connected entities via relations

Inputs: start (required), depth, direction.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool targets a specific operation on the knowledge graph, like creating entities, adding observations, or searching nodes. No two tools have overlapping purposes, ensuring clear distinction for an agent.

    Naming Consistency5/5

    All tools use snake_case with a consistent verb_noun pattern (e.g., create_entities, delete_observations). Minor deviations like 'get_recent' still follow the pattern, making the set predictable.

    Tool Count5/5

    With 13 tools, the server covers core knowledge graph operations without being bloated. Each tool serves a clear purpose, and the count is well-scoped for the domain.

    Completeness4/5

    The tool set includes create, read, delete, and query operations, but lacks dedicated update tools for entities, observations, and relations. While updates can be achieved via delete+create, this is a minor gap.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers