shaneholloman/mcp-knowledge-graph

aim_create_entities

Create multiple new entities in the knowledge graph.

DATABASE SELECTION: By default, all memories are stored in the master database. Use the 'context' parameter to organize information into separate knowledge graphs for different areas of life or work.

STORAGE LOCATION: Files are stored in the user's configured directory, or project-local .aim directory if one exists. Each database creates its own file (e.g., memory-work.jsonl, memory-personal.jsonl).

LOCATION OVERRIDE: Use the 'location' parameter to force storage in a specific location:

• 'project': Always use project-local .aim directory (creates if needed)
• 'global': Always use global configured directory
• Leave blank: Auto-detect (project if .aim exists, otherwise global)

WHEN TO USE DATABASES:

• Any descriptive name: 'work', 'personal', 'health', 'research', 'basket-weaving', 'book-club', etc.
• New databases are created automatically - no setup required
• IMPORTANT: Use consistent, simple names - prefer 'work' over 'work-stuff' or 'job-related'
• Common examples: 'work' (professional), 'personal' (private), 'health' (medical), 'research' (academic)
• Leave blank: General information or when unsure (uses master database)

EXAMPLES:

• Master database (default): aim_create_entities({entities: [{name: "John", entityType: "person", observations: ["Met at conference"]}]})
• Work database: aim_create_entities({context: "work", entities: [{name: "Q4_Project", entityType: "project", observations: ["Due December 2024"]}]})
• Master database in global location: aim_create_entities({location: "global", entities: [{name: "John", entityType: "person", observations: ["Met at conference"]}]})
• Work database in project location: aim_create_entities({context: "work", location: "project", entities: [{name: "Q4_Project", entityType: "project", observations: ["Due December 2024"]}]})

aim_create_relations

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

DATABASE SELECTION: Relations are created within the specified database's knowledge graph. Entities must exist in the same database.

LOCATION OVERRIDE: Use the 'location' parameter to force storage in 'project' (.aim directory) or 'global' (configured directory). Leave blank for auto-detection.

EXAMPLES:

• Master database (default): aim_create_relations({relations: [{from: "John", to: "TechConf2024", relationType: "attended"}]})
• Work database: aim_create_relations({context: "work", relations: [{from: "Alice", to: "Q4_Project", relationType: "manages"}]})
• Master database in global location: aim_create_relations({location: "global", relations: [{from: "John", to: "TechConf2024", relationType: "attended"}]})
• Personal database in project location: aim_create_relations({context: "personal", location: "project", relations: [{from: "Mom", to: "Gardening", relationType: "enjoys"}]})

aim_add_observations

Add new observations to existing entities in the knowledge graph.

DATABASE SELECTION: Observations are added to entities within the specified database's knowledge graph.

LOCATION OVERRIDE: Use the 'location' parameter to force storage in 'project' (.aim directory) or 'global' (configured directory). Leave blank for auto-detection.

EXAMPLES:

• Master database (default): aim_add_observations({observations: [{entityName: "John", contents: ["Lives in Seattle", "Works in tech"]}]})
• Work database: aim_add_observations({context: "work", observations: [{entityName: "Q4_Project", contents: ["Behind schedule", "Need more resources"]}]})
• Master database in global location: aim_add_observations({location: "global", observations: [{entityName: "John", contents: ["Lives in Seattle", "Works in tech"]}]})
• Health database in project location: aim_add_observations({context: "health", location: "project", observations: [{entityName: "Daily_Routine", contents: ["30min morning walk", "8 glasses water"]}]})

aim_delete_entities

Delete multiple entities and their associated relations from the knowledge graph.

DATABASE SELECTION: Entities are deleted from the specified database's knowledge graph.

LOCATION OVERRIDE: Use the 'location' parameter to force deletion from 'project' (.aim directory) or 'global' (configured directory). Leave blank for auto-detection.

EXAMPLES:

• Master database (default): aim_delete_entities({entityNames: ["OldProject"]})
• Work database: aim_delete_entities({context: "work", entityNames: ["CompletedTask", "CancelledMeeting"]})
• Master database in global location: aim_delete_entities({location: "global", entityNames: ["OldProject"]})
• Personal database in project location: aim_delete_entities({context: "personal", location: "project", entityNames: ["ExpiredReminder"]})

aim_delete_observations

Delete specific observations from entities in the knowledge graph.

DATABASE SELECTION: Observations are deleted from entities within the specified database's knowledge graph.

LOCATION OVERRIDE: Use the 'location' parameter to force deletion from 'project' (.aim directory) or 'global' (configured directory). Leave blank for auto-detection.

EXAMPLES:

• Master database (default): aim_delete_observations({deletions: [{entityName: "John", observations: ["Outdated info"]}]})
• Work database: aim_delete_observations({context: "work", deletions: [{entityName: "Project", observations: ["Old deadline"]}]})
• Master database in global location: aim_delete_observations({location: "global", deletions: [{entityName: "John", observations: ["Outdated info"]}]})
• Health database in project location: aim_delete_observations({context: "health", location: "project", deletions: [{entityName: "Exercise", observations: ["Injured knee"]}]})

aim_delete_relations

Delete multiple relations from the knowledge graph.

DATABASE SELECTION: Relations are deleted from the specified database's knowledge graph.

LOCATION OVERRIDE: Use the 'location' parameter to force deletion from 'project' (.aim directory) or 'global' (configured directory). Leave blank for auto-detection.

EXAMPLES:

• Master database (default): aim_delete_relations({relations: [{from: "John", to: "OldCompany", relationType: "worked_at"}]})
• Work database: aim_delete_relations({context: "work", relations: [{from: "Alice", to: "CancelledProject", relationType: "manages"}]})
• Master database in global location: aim_delete_relations({location: "global", relations: [{from: "John", to: "OldCompany", relationType: "worked_at"}]})
• Personal database in project location: aim_delete_relations({context: "personal", location: "project", relations: [{from: "Me", to: "OldHobby", relationType: "enjoys"}]})

aim_read_graph

Read the entire knowledge graph.

DATABASE SELECTION: Reads from the specified database or master database if no database is specified.

LOCATION OVERRIDE: Use the 'location' parameter to force reading from 'project' (.aim directory) or 'global' (configured directory). Leave blank for auto-detection.

EXAMPLES:

• Master database (default): aim_read_graph({})
• Work database: aim_read_graph({context: "work"})
• Master database in global location: aim_read_graph({location: "global"})
• Personal database in project location: aim_read_graph({context: "personal", location: "project"})

aim_search_nodes

Search for nodes in the knowledge graph based on a query.

DATABASE SELECTION: Searches within the specified database or master database if no database is specified.

LOCATION OVERRIDE: Use the 'location' parameter to force searching in 'project' (.aim directory) or 'global' (configured directory). Leave blank for auto-detection.

EXAMPLES:

• Master database (default): aim_search_nodes({query: "John"})
• Work database: aim_search_nodes({context: "work", query: "project"})
• Master database in global location: aim_search_nodes({location: "global", query: "John"})
• Personal database in project location: aim_search_nodes({context: "personal", location: "project", query: "family"})

aim_open_nodes

Open specific nodes in the knowledge graph by their names.

DATABASE SELECTION: Retrieves entities from the specified database or master database if no database is specified.

LOCATION OVERRIDE: Use the 'location' parameter to force retrieval from 'project' (.aim directory) or 'global' (configured directory). Leave blank for auto-detection.

EXAMPLES:

• Master database (default): aim_open_nodes({names: ["John", "TechConf2024"]})
• Work database: aim_open_nodes({context: "work", names: ["Q4_Project", "Alice"]})
• Master database in global location: aim_open_nodes({location: "global", names: ["John", "TechConf2024"]})
• Personal database in project location: aim_open_nodes({context: "personal", location: "project", names: ["Mom", "Birthday_Plans"]})

aim_list_databases

List all available memory databases in both project and global locations.

DISCOVERY: Shows which databases exist, where they're stored, and which location is currently active.

EXAMPLES:

• aim_list_databases() - Shows all available databases and current storage location