In-Memory Knowledge Structure Organizer

Introduction

This utility provides an in-memory mechanism for organizing entities and the defined relationships linking them, which is crucial for structured work tracking. Such knowledge structuring supports complex project management by precisely mapping components, similar to how distinct project tasks must be clearly defined and interconnected to meet final goals.

Setup

To integrate this server into the Claude Desktop environment, execute the subsequent installation command:

mcp install main.py -v MEMORY_FILE_PATH=/path/to/memory.jsonl

Data Validation Rules

Strict criteria govern the input data to maintain graph integrity throughout its lifecycle.

Entity Names

Entity identifiers must adhere to these naming conventions for proper indexing: - They must begin with a character in the lowercase alphabet. - Valid characters include lowercase letters, numeric digits, and the hyphen symbol. - The maximum permitted length for an entity name is one hundred characters. - Each name must be unique within the entire dataset. - Examples of acceptable identifiers are: python-project, meeting-notes-2024, user-john.

Entity Types

The system recognizes and supports the following classifications for data elements: - person: Represents human participants or agents. - concept: Denotes abstract ideas or guiding principles. - project: Classifies defined work initiatives or substantial tasks. - document: Used for various forms of recorded information. - tool: Designates specific software utilities or mechanisms. - organization: Refers to corporate bodies or organized groups. - location: Identifies physical or virtual settings. - event: Marks occurrences associated with specific times.

Observations

Descriptive notes attached to entities must satisfy these constraints: - These fields cannot be empty strings upon entry. - They are limited to a maximum of five hundred characters in length. - Each observation statement must be unique when linked to a single entity. - Statements should maintain an objective and factual tone. - Associating a relevant time stamp with the observation is recommended.

Relations

The connections established between entities must utilize these predefined types: - knows: Indicates a connection between two person entities. - contains: Defines a hierarchical parent-child grouping. - uses: Shows one entity employing another entity. - created: Marks the originator or author of an entity. - belongs-to: Specifies membership or ownership association. - depends-on: Establishes a required predecessor relationship. - related-to: A general category for any remaining associations.

Additional rules governing all constructed relations: - Both the originating and receiving entities must already exist in the graph structure. - An entity cannot form a relationship with itself. - Creating circular dependencies among related items is prohibited. - Only the explicitly defined relation types are permissible for use.

Usage

This server furnishes several methods for interacting with the stored knowledge structure:

Get Entity

To retrieve the details of a specific entity using its unique identifier:

result = await session.call_tool("get_entity", {
    "entity_name": "example"
})
if not result.success:
    if result.error_type == "NOT_FOUND":
        print(f"Entity not found: {result.error}")
    elif result.error_type == "VALIDATION_ERROR":
        print(f"Invalid input: {result.error}")
    else:
        print(f"Error: {result.error}")
else:
    entity = result.data
    print(f"Found entity: {entity}")

Get Graph

This operation allows for the complete retrieval of all currently stored graph data:

result = await session.call_tool("get_graph", {}
if result.success:
    graph = result.data
    print(f"Graph data: {graph}")
else:
    print(f"Error retrieving graph: {result.error}")

Create Entities

Multiple new data elements can be instantiated simultaneously using a list structure:

# Valid entity creation
entities = [
    Entity(
        name="python-project",  # Lowercase with hyphens
        entityType="project",   # Must be a valid type
        observations=["Started development on 2024-01-29"]
    ),
    Entity(
        name="john-doe",
        entityType="person",
        observations=["Software engineer", "Joined team in 2024"]
    )
]
result = await session.call_tool("create_entities", {
    "entities": entities
})
if not result.success:
    if result.error_type == "VALIDATION_ERROR":
        print(f"Invalid entity data: {result.error}")
    else:
        print(f"Error creating entities: {result.error}")

Add Observation

New descriptive statements can be appended to an existing entity record:

# Valid observation
result = await session.call_tool("add_observation", {
    "entity": "python-project",
    "observation": "Completed initial prototype"  # Must be unique for entity
})
if not result.success:
    if result.error_type == "NOT_FOUND":
        print(f"Entity not found: {result.error}")
    elif result.error_type == "VALIDATION_ERROR":
        print(f"Invalid observation: {result.error}")
    else:
        print(f"Error adding observation: {result.error}")

Create Relation

This function establishes a defined link between two previously defined data elements:

# Valid relation
result = await session.call_tool("create_relation", {
    "from_entity": "john-doe",
    "to_entity": "python-project",
    "relation_type": "created"  # Must be a valid type
})
if not result.success:
    if result.error_type == "NOT_FOUND":
        print(f"Entity not found: {result.error}")
    elif result.error_type == "VALIDATION_ERROR":
        print(f"Invalid relation data: {result.error}")
    else:
        print(f"Error creating relation: {result.error}")

Search Memory

This powerful feature allows querying the stored data using text patterns or descriptive phrases:

result = await session.call_tool("search_memory", {
    "query": "most recent workout"  # Supports natural language queries
})
if result.success:
    if result.error_type == "NO_RESULTS":
        print(f"No results found: {result.error}")
    else:
        results = result.data
        print(f"Search results: {results}")
else:
    print(f"Error searching memory: {result.error}")

The search capability supports several query mechanisms: - Temporal inquiries like "most recent" or specifying the "latest" item. - Contextual searches related to activities such as "workout" or "exercise". - General searches targeting entity identifiers directly. - Fuzzy matching is enabled, using an eighty percent similarity threshold. - Weighting determines search relevance across different data fields: - Entity identifiers are matched with a weight factor of 1.0. - Entity classifications receive a weight factor of 0.8. - Associated observations are weighted at 0.6.

Delete Entities

Selected data elements can be purged from the repository by providing a list of their names:

result = await session.call_tool("delete_entities", {
    "names": ["python-project", "john-doe"]
})
if not result.success:
    if result.error_type == "NOT_FOUND":
        print(f"Entity not found: {result.error}")
    else:
        print(f"Error deleting entities: {result.error}")

Delete Relation

Specific links between two elements can be removed using their source and destination entities:

result = await session.call_tool("delete_relation", {
    "from_entity": "john-doe",
    "to_entity": "python-project"
})
if not result.success:
    if result.error_type == "NOT_FOUND":
        print(f"Entity not found: {result.error}")
    else:
        print(f"Error deleting relation: {result.error}")

Flush Memory

This command executes a complete erasure of all stored data within the current session:

result = await session.call_tool("flush_memory", {}
if not result.success:
    print(f"Error flushing memory: {result.error}")

Error Types

When operations fail, the server reports specific error codes for diagnostic purposes:

• NOT_FOUND: Indicates a requested entity or resource is absent.
• VALIDATION_ERROR: Signals that input data failed to meet structural requirements.
• INTERNAL_ERROR: Points to a malfunction within the server's internal processes.
• ALREADY_EXISTS: Occurs if attempting to create an item that is already present.
• INVALID_RELATION: Reports issues with the proposed linkage between two elements.

Response Models

All interactions with the server are structured according to predefined output data structures for predictable handling:

EntityResponse

class EntityResponse(BaseModel):
    success: bool
    data: Optional[Dict[str, Any]] = None
    error: Optional[str] = None
    error_type: Optional[str] = None

GraphResponse

class GraphResponse(BaseModel):
    success: bool
    data: Optional[Dict[str, Any]] = None
    error: Optional[str] = None
    error_type: Optional[str] = None

OperationResponse

class OperationResponse(BaseModel):
    success: bool
    error: Optional[str] = None
    error_type: Optional[str] = None

Development

Procedures are established for maintaining and extending the tool's capabilities.

Running Tests

To confirm system stability, run the integrated test suite from the terminal:

pytest tests/

Adding New Features

Implementing new functionality requires modifications across several specific files: 1. Adjust the necessary validation constraints within the validation.py file. 2. Introduce corresponding verification tests in tests/test_validation.py. 3. Integrate the core logic changes within the knowledge_graph_manager.py file.

Related Topics

• Task dependency management, where sequential completion is required for project progress.
• Coordination, the mechanism linking individual efforts toward a collective goal.
• Data modeling and schema enforcement principles in software design.
• In-memory data structures for high-speed information retrieval.
• Knowledge representation systems using graph theory.

Extra Details

This system strictly guards against ambiguity regarding task completion status. Unlike real-world projects where achieving 90% completion often deceptively implies a small remaining effort, this tool requires explicit definition of all required assignments. Dependency tracking, while vital, must be managed carefully to prevent project stagnation caused by unresolved predecessors. The emphasis on strictly defined types and rules avoids the pitfalls of unclear task definitions.

Conclusion

By enforcing rigorous structural rules upon data elements and their relationships, this utility provides a reliable foundation for tracking complex informational assets. This rigorous organization facilitates better oversight of interconnected work items, improving the overall management and tracking of activities within a defined scope, echoing the need for clear task definitions in project execution.