# API Reference

This document provides a comprehensive reference for all API tools exposed by the Project Memory server.

## Tool Reference

### Entity Management

#### `create_entities`

Creates new entities in the knowledge graph for project components, technologies, or issues.

```json
{
  "name": "create_entities",
  "arguments": {
    "entities": [
      {
        "name": "Frontend_App",
        "entityType": "Component",
        "observations": [
          "React-based SPA with Redux",
          "Uses Material UI components",
          "Responsive design for mobile and desktop"
        ]
      }
    ]
  }
}
```

**Parameters:**
- `entities`: Array of entity objects, each with:
  - `name`: Unique identifier for the entity (PascalCase or snake_case recommended)
  - `entityType`: Type of entity (Project, Component, Technology, Issue, Decision)
  - `observations`: Array of string observations about the entity

**Returns:**
Array of created entities.

#### `delete_entities`

Deletes entities and their associated relations from the knowledge graph.

```json
{
  "name": "delete_entities",
  "arguments": {
    "entityNames": ["UnusedComponent", "DeprecatedTechnology"]
  }
}
```

**Parameters:**
- `entityNames`: Array of entity names to delete

**Returns:**
Confirmation message.

### Relation Management

#### `create_relations`

Creates relations between entities in the knowledge graph.

```json
{
  "name": "create_relations",
  "arguments": {
    "relations": [
      {
        "from": "Project_X",
        "to": "Frontend_App",
        "relationType": "contains"
      },
      {
        "from": "Frontend_App",
        "to": "React",
        "relationType": "uses"
      }
    ]
  }
}
```

**Parameters:**
- `relations`: Array of relation objects, each with:
  - `from`: Name of source entity
  - `to`: Name of target entity
  - `relationType`: Type of relation (contains, uses, depends_on, affected_by, resolved_by, led_to)

**Returns:**
Array of created relations.

#### `delete_relations`

Deletes relations from the knowledge graph.

```json
{
  "name": "delete_relations",
  "arguments": {
    "relations": [
      {
        "from": "Frontend_App",
        "to": "DeprecatedTechnology",
        "relationType": "uses"
      }
    ]
  }
}
```

**Parameters:**
- `relations`: Array of relation objects to delete

**Returns:**
Confirmation message.

### Observation Management

#### `add_observations`

Adds new observations to existing entities.

```json
{
  "name": "add_observations",
  "arguments": {
    "observations": [
      {
        "entityName": "Frontend_App",
        "contents": [
          "Added unit testing with Jest",
          "Implemented dark mode"
        ]
      }
    ]
  }
}
```

**Parameters:**
- `observations`: Array of observation objects, each with:
  - `entityName`: Name of entity to add observations to
  - `contents`: Array of string observations to add

**Returns:**
Details of added observations.

#### `delete_observations`

Deletes specific observations from entities.

```json
{
  "name": "delete_observations",
  "arguments": {
    "deletions": [
      {
        "entityName": "Frontend_App",
        "observations": [
          "Outdated information"
        ]
      }
    ]
  }
}
```

**Parameters:**
- `deletions`: Array of deletion objects, each with:
  - `entityName`: Name of entity containing observations
  - `observations`: Array of observation strings to delete

**Returns:**
Confirmation message.

### Graph Operations

#### `read_graph`

Reads the entire knowledge graph.

```json
{
  "name": "read_graph",
  "arguments": {}
}
```

**Parameters:**
None

**Returns:**
Full knowledge graph with entities and relations.

#### `search_nodes`

Searches for nodes in the knowledge graph.

```json
{
  "name": "search_nodes",
  "arguments": {
    "query": "authentication"
  }
}
```

**Parameters:**
- `query`: Search string to match against entity names, types, and observations

**Returns:**
Filtered knowledge graph with matching entities and their relations.

#### `open_nodes`

Retrieves specific entities by name.

```json
{
  "name": "open_nodes",
  "arguments": {
    "names": ["Frontend_App", "Backend_Service"]
  }
}
```

**Parameters:**
- `names`: Array of entity names to retrieve

**Returns:**
Knowledge graph with specified entities and their relations.

### Software Development Features

#### `find_development_history`

Finds development history for specific components or issues.

```json
{
  "name": "find_development_history",
  "arguments": {
    "entity": "Authentication_Service",
    "entityType": "Component",
    "timeframe": "last_month"
  }
}
```

**Parameters:**
- `entity`: Entity name to find history for
- `entityType`: (Optional) Filter by entity type
- `timeframe`: (Optional) Time filter: "last_day", "last_week", "last_month", or "YYYY-MM-DD:YYYY-MM-DD"

**Returns:**
Knowledge graph with development history.

#### `record_issue`

Records a new issue with detailed information.

```json
{
  "name": "record_issue",
  "arguments": {
    "component": "Frontend_App",
    "description": "Memory leak in image carousel",
    "errorMessage": "React warning: Memory leak detected",
    "status": "Open"
  }
}
```

**Parameters:**
- `component`: Name of component where issue occurs
- `description`: Description of the issue
- `errorMessage`: (Optional) Error message
- `stackTrace`: (Optional) Stack trace
- `status`: Status (Open, In Progress, Resolved, etc.)

**Returns:**
Created issue entity.

#### `get_project_overview`

Gets an overview of the project structure.

```json
{
  "name": "get_project_overview",
  "arguments": {
    "projectName": "E-commerce_Platform"
  }
}
```

**Parameters:**
- `projectName`: Name of project entity

**Returns:**
Knowledge graph with project and related entities.

#### `get_related_entities`

Gets entities related to a specific entity.

```json
{
  "name": "get_related_entities",
  "arguments": {
    "entityName": "Authentication_Service",
    "depth": 2
  }
}
```

**Parameters:**
- `entityName`: Name of entity to find relations for
- `depth`: (Optional) How many relation hops to traverse (default: 1)

**Returns:**
Knowledge graph with related entities.

## Entity Types

The system supports these entity types:

- **Project**: Root node for a software project
- **Component**: Software component (service, module, library, etc.)
- **Technology**: Framework, language, or library
- **Issue**: Bug, error, or technical challenge
- **Decision**: Architectural or implementation decision

## Relation Types

The system supports these relation types:

- **contains**: Hierarchical relationship (Project contains Component)
- **uses**: Implementation relationship (Component uses Technology)
- **depends_on**: Dependency relationship (Component depends on Component)
- **affected_by**: Issue relationship (Component affected by Issue)
- **resolved_by**: Resolution relationship (Issue resolved by Decision)
- **led_to**: Consequence relationship (Decision led to Decision)
- **implements**: Implementation relationship (Component implements Feature)
- **supersedes**: Replacement relationship (Component supersedes Component)