Skip to main content
Glama
deenesjakoruzh
shaneholloman

mcp-knowledge-graph

by shaneholloman
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Hybrid

MCP Knowledge Graph

Persistent memory for AI models through a local knowledge graph.

Store and retrieve information across conversations using entities, relations, and observations. Works with Claude Code/Desktop and any MCP-compatible AI platform.

Why ".aim" and "aim_" prefixes?

AIM stands for AI Memory - the core concept of this system. The three AIM elements provide clear organization and safety:

  • .aim directories: Keep AI memory files organized and easily identifiable

  • aim_ tool prefixes: Group related memory functions together in multi-tool setups

  • _aim safety markers: Each memory file starts with {"type":"_aim","source":"mcp-knowledge-graph"} to prevent accidental overwrites of unrelated JSONL files

This consistent AIM naming makes it obvious which directories, tools, and files belong to the AI memory system.

Related MCP server: Knowledge Graph Memory Server

CRITICAL: Understanding .aim dir vs _aim file marker

Two different things with similar names:

  • .aim = Project-local directory name (MUST be named exactly .aim for project detection to work)

  • _aim = File safety marker (appears inside JSONL files: {"type":"_aim","source":"mcp-knowledge-graph"})

For project-local storage:

  • Directory MUST be named .aim in your project root

  • Example: my-project/.aim/memory.jsonl

  • The system specifically looks for this exact name

For global storage (--memory-path):

  • Can be ANY directory you want

  • Examples: ~/yourusername/.aim/, ~/memories/, ~/Dropbox/ai-memory/, ~/Documents/ai-data/

  • Complete flexibility - choose whatever location works for you

Storage Logic

File Location Priority:

  1. Project with .aim - Uses .aim/memory.jsonl (project-local)

  2. No project/no .aim - Uses configured global directory

  3. Contexts - Adds suffix: memory-work.jsonl, memory-personal.jsonl

Safety System:

  • Every memory file starts with {"type":"_aim","source":"mcp-knowledge-graph"}

  • System refuses to write to files without this marker

  • Prevents accidental overwrite of unrelated JSONL files

Master Database Concept

The master database is your primary memory store - used by default when no specific database is requested. It's always named default in listings and stored as memory.jsonl.

  • Default Behavior: All memory operations use the master database unless you specify a different one

  • Always Available: Exists in both project-local and global locations

  • Primary Storage: Your main knowledge graph that persists across all conversations

  • Named Databases: Optional additional databases (work, personal, health) for organizing specific topics

Key Features

  • Master Database: Primary memory store used by default for all operations

  • Multiple Databases: Optional named databases for organizing memories by topic

  • Project Detection: Automatic project-local memory using .aim directories

  • Location Override: Force operations to use project or global storage

  • Safe Operations: Built-in protection against overwriting unrelated files

  • Database Discovery: List all available databases in both locations

Quick Start

Global Memory (Recommended)

Add to your claude_desktop_config.json or .claude.json. Two common approaches:

Option 1: Default .aim directory (simple)

{
  "mcpServers": {
    "Aim-Memory-Bank": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-knowledge-graph",
        "--memory-path",
        "/Users/yourusername/.aim"
      ]
    }
  }
}

Option 2: Dropbox/cloud sync (portable)

For accessing memories across multiple machines, use a synced folder. This is how the author of this MCP server keeps his own memories:

{
  "mcpServers": {
    "Aim-Memory-Bank": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-knowledge-graph",
        "--memory-path",
        "/Users/yourusername/Dropbox/ai-memory"
      ]
    }
  }
}

This creates memory files in your specified directory:

  • memory.jsonl - Master Database (default for all operations)

  • memory-work.jsonl - Work database

  • memory-personal.jsonl - Personal database

  • etc.

Project-Local Memory

In any project, create a .aim directory:

mkdir .aim

Now memory tools automatically use .aim/memory.jsonl (project-local master database) instead of global storage when run from this project.

How AI Uses Databases

Once configured, AI models use the master database by default or can specify named databases with a context parameter. New databases are created automatically - no setup required:

// Master Database (default - no context needed)
aim_memory_store({
  entities: [{
    name: "John_Doe",
    entityType: "person",
    observations: ["Met at conference"]
  }]
})

// Work database
aim_memory_store({
  context: "work",
  entities: [{
    name: "Q4_Project",
    entityType: "project",
    observations: ["Due December 2024"]
  }]
})

// Personal database
aim_memory_store({
  context: "personal",
  entities: [{
    name: "Mom",
    entityType: "person",
    observations: ["Birthday March 15th"]
  }]
})

// Master database in specific location
aim_memory_store({
  location: "global",
  entities: [{
    name: "Important_Info",
    entityType: "reference",
    observations: ["Stored in global master database"]
  }]
})

File Organization

Global Setup:

/Users/yourusername/.aim/
├── memory.jsonl           # Master Database (default)
├── memory-work.jsonl      # Work database
├── memory-personal.jsonl  # Personal database
└── memory-health.jsonl    # Health database

Project Setup:

my-project/
├── .aim/
│   ├── memory.jsonl       # Project Master Database (default)
│   └── memory-work.jsonl  # Project Work database
└── src/

Available Tools

  • aim_memory_store - Store new memories (people, projects, concepts)

  • aim_memory_add_facts - Add facts to existing memories

  • aim_memory_link - Link two memories together

  • aim_memory_search - Search memories by keyword

  • aim_memory_get - Retrieve specific memories by exact name

  • aim_memory_read_all - Read all memories in a database

  • aim_memory_list_stores - List available databases

  • aim_memory_forget - Forget memories

  • aim_memory_remove_facts - Remove specific facts from a memory

  • aim_memory_unlink - Remove links between memories

Parameters

  • context (optional) - Specify named database (work, personal, etc.). Defaults to master database

  • location (optional) - Force project or global storage location. Defaults to auto-detection

Database Discovery

Use aim_memory_list_stores to see all available databases:

{
  "project_databases": [
    "default",      // Master Database (project-local)
    "project-work"  // Named database
  ],
  "global_databases": [
    "default",      // Master Database (global)
    "work",
    "personal",
    "health"
  ],
  "current_location": "project (.aim directory detected)"
}

Key Points:

  • "default" = Master Database in both locations

  • Current location shows whether you're using project or global storage

  • Master database exists everywhere - it's your primary memory store

  • Named databases are optional additions for specific topics

Configuration Examples

Important: Always specify --memory-path to control where your memory files are stored.

Auto-approve read operations (recommended):

{
  "mcpServers": {
    "Aim-Memory-Bank": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-knowledge-graph",
        "--memory-path",
        "/Users/yourusername/.aim"
      ],
      "autoapprove": [
        "aim_memory_search",
        "aim_memory_get",
        "aim_memory_read_all",
        "aim_memory_list_stores"
      ]
    }
  }
}

Troubleshooting

"File does not contain required _aim safety marker" error:

  • The file may not belong to this system

  • Manual JSONL files need {"type":"_aim","source":"mcp-knowledge-graph"} as first line

  • If you created the file manually, add the _aim marker or delete and let the system recreate it

Memories going to unexpected locations:

  • Check if you're in a project directory with .aim folder (uses project-local storage)

  • Otherwise uses the configured global --memory-path directory

  • Use aim_memory_list_stores to see all available databases and current location

  • Use ls .aim/ or ls /Users/yourusername/.aim/ to see your memory files

Too many similar databases:

  • AI models try to use consistent names, but may create variations

  • Manually delete unwanted database files if needed

  • Encourage AI to use simple, consistent database names

  • Remember: Master database is always available as the default - named databases are optional

Requirements

  • Node.js 22+

  • MCP-compatible AI platform

License

MIT

Available Tools

10 tools
aim_memory_add_factsA

Add new facts to an existing memory. Use this to append information to something already stored.

IMPORTANT: Memory must already exist - use aim_memory_store first. Throws error if not found.

RETURNS: Array of {entityName, addedObservations} showing what was added (duplicates are ignored).

DATABASE: Adds to entities in the specified 'context' database, or master database if not specified.

EXAMPLES:

  • aim_memory_add_facts({observations: [{entityName: "John", contents: ["Lives in Seattle", "Works in tech"]}]})

  • aim_memory_add_facts({context: "work", observations: [{entityName: "Q4_Project", contents: ["Behind schedule", "Need more resources"]}]})

ParametersJSON Schema
NameRequiredDescriptionDefault
contextNoOptional memory context. Observations will be added to entities in the specified context's knowledge graph.
locationNoOptional storage location override. 'project' forces project-local .aim directory, 'global' forces global directory. If not specified, uses automatic detection.
observationsYes

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite no annotations, the description discloses key behaviors: duplicates are ignored, returns an array of {entityName, addedObservations}, and database context (adds to specified or master database). No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is concise with a clear structure: purpose, important note, return value, database context, and examples. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately explains return format and behavior. It covers error handling, database context, and duplicate handling. Sufficient for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67% with descriptions, but the description adds value by explaining the return format for observations and providing examples that clarify parameter usage. The baseline is 3 due to schema coverage, but examples elevate it to 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool adds new facts to an existing memory, distinguishing it from sibling tools like aim_memory_store (creates new memory) and aim_memory_remove_facts (removes facts). The verb 'add' and resource 'facts' are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states that memory must already exist and to use aim_memory_store first, plus that it throws an error if not found. Provides clear when-to-use and preconditions. Examples further guide usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

aim_memory_forgetA

Forget memories. Removes memories and their associated links.

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_memory_forget({entityNames: ["OldProject"]})

  • Work database: aim_memory_forget({context: "work", entityNames: ["CompletedTask", "CancelledMeeting"]})

  • Master database in global location: aim_memory_forget({location: "global", entityNames: ["OldProject"]})

  • Personal database in project location: aim_memory_forget({context: "personal", location: "project", entityNames: ["ExpiredReminder"]})

ParametersJSON Schema
NameRequiredDescriptionDefault
contextNoOptional memory context. Entities will be deleted from the specified context's knowledge graph.
locationNoOptional storage location override. 'project' forces project-local .aim directory, 'global' forces global directory. If not specified, uses automatic detection.
entityNamesYesAn array of entity names to delete

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must cover behavioral traits. It explains that entities are deleted from the knowledge graph and that associated links are also removed. It discusses location override and auto-detection. However, it does not mention irreversibility or return status, which would enhance transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections for database selection and location override, and includes four examples. While it is a bit lengthy, the information is organized and front-loaded, making it easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the operation and parameter details thoroughly but lacks information about the return value or what happens after deletion (e.g., success/failure reporting). Given no output schema, additional context on the outcome would improve completeness for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All three parameters are described in the schema, and the description adds significant value: context usage is clarified (optional, for specific contexts), location parameter includes explanation of enum values and override behavior, and entityNames is shown in examples with appropriate syntax. The description goes beyond schema definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'forget' and resource 'memories', clearly indicating deletion. It differentiates from siblings like aim_memory_store, aim_memory_get, and aim_memory_remove_facts by specifying that it removes both memories and their associated links.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use the tool with database selection methods (context, location override) and provides multiple examples covering different scenarios (default, work database, global location, etc.). It does not explicitly mention when not to use, but the context and examples sufficiently guide usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

aim_memory_getA

Retrieve specific memories by exact name. Use this when you know exactly what you're looking for.

VS aim_memory_search: Use aim_memory_get for exact name lookup. Use aim_memory_search for fuzzy matching or when you don't know exact names.

RETURNS: Requested entities and relations between them. Non-existent names are silently ignored.

FORMAT OPTIONS:

  • "json" (default): Structured JSON for programmatic use

  • "pretty": Human-readable text format

EXAMPLES:

  • aim_memory_get({names: ["John", "TechConf2024"]}) - JSON format

  • aim_memory_get({names: ["Shane"], format: "pretty"}) - Human-readable

  • aim_memory_get({context: "work", names: ["Q4_Project"], format: "pretty"})

ParametersJSON Schema
NameRequiredDescriptionDefault
contextNoOptional memory context. Retrieves entities from the specified context's knowledge graph or master database if not specified.
locationNoOptional storage location override. 'project' for .aim directory, 'global' for configured directory.
namesYesAn array of entity names to retrieve
formatNoOutput format. 'json' (default) for structured data, 'pretty' for human-readable text.

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries burden. Discloses silent ignoring of missing names and format options. For a read-only tool, this is sufficient, though could mention safety or auth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear sections, examples, and sibling differentiation. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all parameters, format, examples, sibling comparison, and return values (entities and relations). Complete for a retrieval tool with no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%. Description adds value with examples and explanation of format options and context parameter, going beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it retrieves specific memories by exact name. Distinguishes from sibling aim_memory_search by specifying exact vs fuzzy matching.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use (exact name known) and when not (use aim_memory_search for fuzzy). Also notes non-existent names are silently ignored.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

aim_memory_list_storesA

List all available memory databases and show current storage location.

DATABASE TYPES:

  • "default": The master database (memory.jsonl) - used when no context is specified

  • Named databases: Created via context parameter (e.g., "work" -> memory-work.jsonl)

RETURNS: {project_databases: [...], global_databases: [...], current_location: "..."}

  • project_databases: Databases in .aim directory (if project detected)

  • global_databases: Databases in global --memory-path directory

  • current_location: Where operations will default to

Use this to discover what databases exist before querying them.

EXAMPLES:

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

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses database types, naming conventions, and the structure of the return object. No behavioral traits like side effects or permissions are mentioned, but the tool appears read-only and harmless.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (DATABASE TYPES, RETURNS, EXAMPLES). Every sentence adds meaningful information, and the format is easily scannable. No fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and no output schema, the description fully covers what the tool does, what it returns, and provides an example usage. It is sufficient for an agent to invoke correctly without additional context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters, so the baseline is 4. Description adds value by explaining database types and the return format, which helps the agent understand the output without needing explicit parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses specific verb 'list' and clearly identifies the resource as 'available memory databases and show current storage location'. It distinguishes itself from sibling tools that perform mutations or queries on individual memories.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states 'Use this to discover what databases exist before querying them', providing clear context for when to invoke this tool. No exclusions or alternatives are given, but the single use case is well-defined.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

aim_memory_read_allA

Read all memories in a database. Returns every stored memory and their links.

FORMAT OPTIONS:

  • "json" (default): Structured JSON for programmatic use

  • "pretty": Human-readable text format

DATABASE: Reads from the specified 'context' database, or master database if not specified.

EXAMPLES:

  • aim_memory_read_all({}) - JSON format

  • aim_memory_read_all({format: "pretty"}) - Human-readable

  • aim_memory_read_all({context: "work", format: "pretty"}) - Work database, pretty

ParametersJSON Schema
NameRequiredDescriptionDefault
contextNoOptional memory context. Reads from the specified context's knowledge graph or master database if not specified.
locationNoOptional storage location override. 'project' for .aim directory, 'global' for configured directory.
formatNoOutput format. 'json' (default) for structured data, 'pretty' for human-readable text.

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided. The description does not disclose potential performance impacts for large databases or that this is a read-only operation (though implied by name). It adds some context via format options but misses behavioral traits like rate limits or idempotency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections for format options, database info, and examples. It is concise with no redundant sentences; every part adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains what is returned (memories and links) and provides format options. Without an output schema, it is somewhat vague about the structure, but the examples and format choices compensate. It is sufficient for a read-all tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage, but the description enhances understanding by explaining the format parameter with examples and clarifying the context parameter's effect. It goes beyond the schema by providing usage examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads all memories and returns them with their links. The verb 'Read' and resource 'all memories' are specific. It distinguishes from sibling tools like aim_memory_get (likely single memory) and aim_memory_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on database selection (context) and format options (json/pretty) with examples. It implies when to use: when you need all memories. However, it does not explicitly state when not to use or compare with alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

aim_memory_remove_factsA

Remove specific facts from a memory. Keeps the memory but removes selected observations.

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_memory_remove_facts({deletions: [{entityName: "John", observations: ["Outdated info"]}]})

  • Work database: aim_memory_remove_facts({context: "work", deletions: [{entityName: "Project", observations: ["Old deadline"]}]})

  • Master database in global location: aim_memory_remove_facts({location: "global", deletions: [{entityName: "John", observations: ["Outdated info"]}]})

  • Health database in project location: aim_memory_remove_facts({context: "health", location: "project", deletions: [{entityName: "Exercise", observations: ["Injured knee"]}]})

ParametersJSON Schema
NameRequiredDescriptionDefault
contextNoOptional memory context. Observations will be deleted from entities in the specified context's knowledge graph.
locationNoOptional storage location override. 'project' forces project-local .aim directory, 'global' forces global directory. If not specified, uses automatic detection.
deletionsYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It clearly states that the memory is kept while only selected observations are removed. It explains the database selection behavior and location override logic. However, it does not mention error handling (e.g., if observations don't exist) or permissions, but the core behavior is well disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections (DATABASE SELECTION, LOCATION OVERRIDE, EXAMPLES) and uses bullet-like formatting. It avoids tautology and provides necessary context. While slightly lengthy due to examples, each part adds value. Could be more concise, but it's organized and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 3 parameters, no output schema, and no annotations, the description covers the main behaviors: what the tool does, database/location selection, and multiple examples. It lacks explicit details on error cases or return values, but it is sufficient for an agent to invoke the tool correctly in most scenarios.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 67% (context and location have descriptions, deletions does not at top level). The description adds value by explaining the deletions parameter through examples and stating that it removes selected observations. It clarifies the structure (array of objects with entityName and observations) and provides multiple usage patterns, enhancing understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Remove specific facts from a memory. Keeps the memory but removes selected observations.' This distinguishes it from siblings like aim_memory_forget (which likely removes entire memory) and aim_memory_add_facts (adds). The verb 'remove' and resource 'facts from a memory' are specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use the location override and includes examples for different contexts (master, work, health) and locations (project, global). It implies the tool is for selective deletion without removing the entire memory, but does not explicitly state when not to use it compared to siblings like aim_memory_forget. The database selection section also adds context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

aim_memory_storeA

Store new memories. Use this to remember people, projects, concepts, or any information worth persisting.

AIM (AI Memory) provides persistent memory for AI assistants. The 'aim_memory_' prefix groups all memory tools together.

WHAT'S STORED: Memories have a name, type (person/project/concept/etc.), and observations (facts about them).

DATABASES: Use the 'context' parameter to organize memories into separate graphs:

  • Leave blank: Uses the master database (default for general information)

  • Any name: Creates/uses a named database ('work', 'personal', 'health', 'research', etc.)

  • New databases are created automatically - no setup required

  • IMPORTANT: Use consistent, simple names - prefer 'work' over 'work-stuff'

STORAGE LOCATIONS: Files are stored as JSONL (e.g., memory.jsonl, memory-work.jsonl):

  • Project-local: .aim directory in project root (auto-detected if exists)

  • Global: User's configured --memory-path directory

  • Use 'location' parameter to override: 'project' or 'global'

RETURNS: Array of created entities.

EXAMPLES:

  • Master database (default): aim_memory_store({entities: [{name: "John", entityType: "person", observations: ["Met at conference"]}]})

  • Work database: aim_memory_store({context: "work", entities: [{name: "Q4_Project", entityType: "project", observations: ["Due December 2024"]}]})

  • Master database in global location: aim_memory_store({location: "global", entities: [{name: "John", entityType: "person", observations: ["Met at conference"]}]})

  • Work database in project location: aim_memory_store({context: "work", location: "project", entities: [{name: "Q4_Project", entityType: "project", observations: ["Due December 2024"]}]})

ParametersJSON Schema
NameRequiredDescriptionDefault
contextNoOptional memory context. Defaults to master database if not specified. Use any descriptive name ('work', 'personal', 'health', 'basket-weaving', etc.) - new contexts created automatically.
locationNoOptional storage location override. 'project' forces project-local .aim directory, 'global' forces global directory. If not specified, uses automatic detection.
entitiesYes

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description thoroughly discloses behavioral traits: it explains the structure of memories (name, type, observations), the use of 'context' for databases, storage mechanisms (JSONL files, .aim directory, global), and return value (array of created entities). Since no annotations are provided, the description fully covers transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (WHAT'S STORED, DATABASES, etc.) and front-loaded with the core purpose. While concise for the complexity, it could be slightly trimmed without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (3 parameters, nested array) and absence of output schema, the description covers all necessary aspects: purpose, parameters, usage patterns, storage details, return values, and examples. It is complete and self-contained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds significant meaning beyond the input schema. For 'context', it explains master database and naming conventions. For 'location', it clarifies project/global and automatic detection. For 'entities', it details the nested object structure. Schema coverage is high, but the description enhances understanding with practical guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Store new memories... remember people, projects, concepts, or any information worth persisting.' It specifies the verb (store) and resource (memories), and the sibling tools (like aim_memory_add_facts or aim_memory_forget) have different purposes, making it distinguishable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides guidance on when to use the tool (to remember information) and includes examples for different scenarios (master database, named context, location). However, it does not explicitly state when not to use it or directly reference sibling tools for alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation5/5

Each tool has a distinct action—store, retrieve, search, list, link, unlink, etc.—with no overlapping purposes. The descriptions clearly differentiate similar tools like get vs search and read_all vs list_stores.

Naming Consistency5/5

All tools use the consistent prefix 'aim_memory_' followed by a clear snake_case action verb (store, add_facts, get, search, read_all, list_stores, forget, remove_facts, link, unlink). No mixing of styles.

Tool Count5/5

10 tools cover the essential operations for a knowledge graph memory system—CRUD for entities and relations, plus search and listing. This is well-scoped without being excessive or sparse.

Completeness4/5

The tool set covers creation, retrieval, search, listing, linking, and deletion of entities and facts. Missing is a direct update for entity names or types (requires forget+re-store), but this is a minor gap given the add/remove facts functionality.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/shaneholloman/mcp-knowledge-graph'

If you have feedback or need assistance with the MCP directory API, please join our Discord server