# Intelligence & Skills API

Endpoints for memory systems, skills marketplace, ClawHub, hands automation, extensions, plugins, and media generation.

## Memory Endpoints

LibreFang provides two memory systems: a simple key-value store per agent and a proactive semantic memory system (mem0-style) with relationship graphs and decay.

### GET /api/memory/agents/&lbrace;id&rbrace;/kv

List all key-value pairs for an agent.

**Response** `200 OK`:

```json
{
  "kv_pairs": [
    {"key": "preferences", "value": {"theme": "dark"}},
    {"key": "state", "value": {"step": 3}}
  ]
}
```

### GET /api/memory/agents/&lbrace;id&rbrace;/kv/&lbrace;key&rbrace;

Get a specific key-value pair.

**Response** `200 OK`:

```json
{
  "key": "preferences",
  "value": {"theme": "dark"}
}
```

**Response** `404 Not Found` (key does not exist):

```json
{
  "error": "Key 'preferences' not found"
}
```

### PUT /api/memory/agents/&lbrace;id&rbrace;/kv/&lbrace;key&rbrace;

Set a key-value pair. Creates or overwrites.

**Request Body**:

```json
{
  "value": {"theme": "dark", "language": "en"}
}
```

**Response** `200 OK`:

```json
{
  "status": "stored",
  "key": "preferences"
}
```

### DELETE /api/memory/agents/&lbrace;id&rbrace;/kv/&lbrace;key&rbrace;

Delete a key-value pair.

**Response** `200 OK`:

```json
{
  "status": "deleted",
  "key": "preferences"
}
```

### GET /api/memory

List all proactive memory entries (global, across agents and users).

### POST /api/memory

Add a new proactive memory entry.

**Request Body**:

```json
{
  "content": "User prefers concise answers",
  "agent_id": "a1b2c3d4-...",
  "user_id": "user-1",
  "tags": ["preference"]
}
```

### GET /api/memory/search

Search proactive memory using semantic similarity.

**Query Parameters:**
- `q` (required): Search query string
- `agent_id` (optional): Limit to a specific agent
- `limit` (optional): Max results (default: 10)

### GET /api/memory/stats

Get aggregate statistics for the proactive memory store.

### POST /api/memory/cleanup

Remove expired or stale memory entries.

### POST /api/memory/decay

Apply time-decay to memory entry scores (reduces relevance of old entries).

### POST /api/memory/bulk-delete

Delete multiple memory entries by ID list.

### PUT /api/memory/items/&lbrace;memory_id&rbrace;

Update a specific memory entry.

### DELETE /api/memory/items/&lbrace;memory_id&rbrace;

Delete a specific memory entry.

### GET /api/memory/items/&lbrace;memory_id&rbrace;/history

Get the edit history for a specific memory entry.

### GET /api/memory/user/&lbrace;user_id&rbrace;

Get all memory entries associated with a user.

### GET /api/memory/agents/&lbrace;id&rbrace;

List all proactive memory entries for a specific agent.

### DELETE /api/memory/agents/&lbrace;id&rbrace;

Delete all proactive memory entries for a specific agent.

### GET /api/memory/agents/&lbrace;id&rbrace;/search

Search proactive memory for a specific agent.

### GET /api/memory/agents/&lbrace;id&rbrace;/stats

Get memory statistics for a specific agent.

### DELETE /api/memory/agents/&lbrace;id&rbrace;/level/&lbrace;level&rbrace;

Clear all memory entries at a specific importance level for an agent.

### GET /api/memory/agents/&lbrace;id&rbrace;/duplicates

Find duplicate memory entries for an agent.

### POST /api/memory/agents/&lbrace;id&rbrace;/consolidate

Consolidate and deduplicate memory entries for an agent.

### GET /api/memory/agents/&lbrace;id&rbrace;/count

Get the total memory entry count for an agent.

### GET /api/memory/agents/&lbrace;id&rbrace;/relations

Query relationship graph entries for an agent.

### POST /api/memory/agents/&lbrace;id&rbrace;/relations

Store new relationship graph entries for an agent.

### GET /api/memory/agents/&lbrace;id&rbrace;/export

Export all proactive memory entries for an agent as JSON.

### POST /api/memory/agents/&lbrace;id&rbrace;/import

Import proactive memory entries for an agent from JSON.

---

## Skills & Marketplace Endpoints

Manage the skill registry. Skills extend agent capabilities with Python, Node.js, WASM, or prompt-only modules. All skill installations go through SHA256 verification and prompt injection scanning.

### GET /api/skills

List all installed skills. Supports optional category filtering.

**Query Parameters:**
- `category` (optional): Filter by skill category tag (e.g., `devops`, `data`)

**Response** `200 OK`:

```json
{
  "skills": [
    {
      "name": "github",
      "version": "1.0.0",
      "runtime": "PromptOnly",
      "description": "GitHub integration for issues, PRs, and repos",
      "author": "librefang",
      "tags": ["devtools"],
      "tools_count": 0,
      "enabled": true,
      "has_prompt_context": true,
      "source": {"type": "local"}
    }
  ],
  "total": 60,
  "categories": ["ai-ml", "cloud", "data", "devtools", "general"]
}
```

### POST /api/skills/install

Install a skill from a local path or URL. The skill manifest is verified (SHA256 checksum) and scanned for prompt injection before installation.

**Request Body**:

```json
{
  "source": "/path/to/skill",
  "verify": true
}
```

**Response** `201 Created`:

```json
{
  "status": "installed",
  "skill": "my-custom-skill",
  "version": "1.0.0"
}
```

### POST /api/skills/uninstall

Remove an installed skill. Bundled skills cannot be uninstalled.

**Request Body**:

```json
{
  "name": "my-custom-skill"
}
```

**Response** `200 OK`:

```json
{
  "status": "uninstalled",
  "skill": "my-custom-skill"
}
```

### POST /api/skills/create

Create a new prompt-only skill via the evolution module. The skill is validated, security-scanned, and hot-reloaded into the registry immediately.

**Request Body**:

```json
{
  "name": "csv-analysis",
  "description": "Expert CSV data analysis and cleaning workflows",
  "prompt_context": "# CSV Analysis\n\nWhen analyzing CSV files...",
  "tags": ["data", "csv"]
}
```

**Response** `200 OK`:

```json
{
  "status": "created",
  "name": "csv-analysis",
  "version": "0.1.0",
  "message": "Skill 'csv-analysis' created successfully"
}
```

### GET /api/skills/&lbrace;name&rbrace;

Get detailed information about a specific skill, including evolution history, tools, supporting files, and usage metrics.

**Response** `200 OK`:

```json
{
  "name": "csv-analysis",
  "version": "0.1.2",
  "description": "Expert CSV data analysis and cleaning workflows",
  "author": "agent-evolved",
  "license": "",
  "tags": ["data", "csv"],
  "runtime": "PromptOnly",
  "tools": [],
  "has_prompt_context": true,
  "prompt_context_length": 2450,
  "source": "Local",
  "enabled": true,
  "path": "/home/user/.librefang/skills/csv-analysis",
  "linked_files": {
    "references": ["pandas-cheatsheet.md"],
    "templates": ["clean.py"]
  },
  "evolution": {
    "versions": [
      {
        "version": "0.1.0",
        "timestamp": "2026-04-16T12:00:00Z",
        "changelog": "Initial creation by agent",
        "content_hash": "a1b2c3..."
      },
      {
        "version": "0.1.2",
        "timestamp": "2026-04-16T14:30:00Z",
        "changelog": "Added encoding detection step",
        "content_hash": "d4e5f6..."
      }
    ],
    "use_count": 12,
    "evolution_count": 3
  }
}
```

**Response** `404 Not Found`:

```json
{
  "error": "Skill 'nonexistent' not found"
}
```

### GET /api/marketplace/search

Search the FangHub marketplace for community skills.

**Query Parameters:**
- `q` (required): Search query string
- `page` (optional): Page number (default: 1)

**Response** `200 OK`:

```json
{
  "results": [
    {
      "name": "weather-api",
      "author": "community",
      "description": "Real-time weather data integration",
      "downloads": 1250,
      "version": "2.1.0"
    }
  ],
  "total": 1,
  "page": 1
}
```

---

## ClawHub Endpoints

Browse and install skills from ClawHub (OpenClaw ecosystem compatibility). All installations go through the full security pipeline: SHA256 verification, SKILL.md security scanning, and trust boundary enforcement.

### GET /api/clawhub/search

Search ClawHub for compatible skills.

**Query Parameters:**
- `q` (required): Search query

### GET /api/clawhub/browse

Browse ClawHub categories.

**Query Parameters:**
- `category` (optional): Filter by category
- `page` (optional): Page number (default: 1)

### GET /api/clawhub/skill/&lbrace;slug&rbrace;

Get detailed information about a specific ClawHub skill.

### GET /api/clawhub/skill/&lbrace;slug&rbrace;/code

Get the raw source code of a ClawHub skill.

### POST /api/clawhub/install

Install a skill from ClawHub. Downloads, verifies SHA256 checksum, scans for prompt injection, and converts SKILL.md format to LibreFang skill.toml automatically.

**Request Body**:

```json
{
  "slug": "data-pipeline"
}
```

**Response** `201 Created`:

```json
{
  "status": "installed",
  "skill": "data-pipeline",
  "version": "1.2.0",
  "converted_from": "SKILL.md"
}
```

---

## Hands Endpoints

Hands are persistent automation processes (browser automation, RPA, long-running bots) managed by the kernel.

### GET /api/hands

List all installed hand definitions.

### POST /api/hands/install

Install a hand from a manifest or registry slug.

### GET /api/hands/active

List currently active (running) hand instances.

### GET /api/hands/&lbrace;hand_id&rbrace;

Get detailed information about a specific hand definition.

### POST /api/hands/&lbrace;hand_id&rbrace;/activate

Activate a hand, creating a new running instance.

### POST /api/hands/&lbrace;hand_id&rbrace;/check-deps

Check whether all dependencies required by a hand are installed.

### POST /api/hands/&lbrace;hand_id&rbrace;/install-deps

Install missing dependencies for a hand.

### GET /api/hands/&lbrace;hand_id&rbrace;/settings

Get the current settings for a hand.

### PUT /api/hands/&lbrace;hand_id&rbrace;/settings

Update the settings for a hand.

### POST /api/hands/instances/&lbrace;id&rbrace;/pause

Pause a running hand instance.

### POST /api/hands/instances/&lbrace;id&rbrace;/resume

Resume a paused hand instance.

### DELETE /api/hands/instances/&lbrace;id&rbrace;

Deactivate and remove a hand instance.

### GET /api/hands/instances/&lbrace;id&rbrace;/stats

Get runtime statistics for a hand instance (uptime, events processed, errors).

### GET /api/hands/instances/&lbrace;id&rbrace;/browser

Get the current browser state for a browser-automation hand instance.

---

## Extensions Endpoints

Extensions add new capabilities to the daemon itself (custom tools, routes, integrations) without modifying core code.

### GET /api/extensions

List all installed extensions.

### GET /api/extensions/&lbrace;name&rbrace;

Get information about a specific extension.

### POST /api/extensions/install

Install an extension from a path or registry.

### POST /api/extensions/uninstall

Uninstall an extension by name.

---

## Plugins Endpoints

Context engine plugins extend the context assembly pipeline (RAG, preprocessing, document loaders, etc.).

### GET /api/plugins/registries

List configured plugin registries (local and remote).

### GET /api/plugins

List all installed plugins.

### GET /api/plugins/&lbrace;name&rbrace;

Get information about a specific plugin.

### POST /api/plugins/install

Install a plugin from a registry or local path.

### POST /api/plugins/uninstall

Uninstall a plugin by name.

### POST /api/plugins/scaffold

Scaffold a new plugin project from a template. Body: `{"name": "...", "description": "...", "runtime": "python" | "native" | "v" | "node" | "deno" | "go" | "ruby" | "bash" | "bun" | "php" | "lua"}`. Emits hook scaffolding in the chosen language.

### GET /api/plugins/doctor

Probe every supported runtime for its launcher on PATH and cross-reference with every installed plugin. Response includes each runtime's detected version + install hint, and flags any plugin whose declared runtime is unavailable. Use this to debug plugins that silently do nothing.

### POST /api/plugins/&lbrace;name&rbrace;/install-deps

Install runtime dependencies for a plugin (e.g., Python packages, Node modules).

---

## Media Generation Endpoints

Provider-agnostic media generation — image, text-to-speech, video, and music. LibreFang auto-detects the first configured provider for each capability, or you can specify a provider explicitly via the `provider` field.

Supported providers: **OpenAI** (image, TTS), **MiniMax** (image, TTS, video, music).

### POST /api/media/image

Generate one or more images from a text prompt.

**Request Body**:

```json
{
  "prompt": "A futuristic city skyline at sunset",
  "provider": "openai",
  "model": "gpt-image-1",
  "width": 1024,
  "height": 1024,
  "count": 1
}
```

All fields except `prompt` are optional. If `provider` is omitted, the first configured provider with image capability is used.

**Response** `200 OK`:

```json
{
  "images": [
    { "url": "/api/uploads/550e8400-..." }
  ],
  "model": "gpt-image-1",
  "provider": "openai",
  "revised_prompt": "A detailed futuristic city..."
}
```

### POST /api/media/speech

Synthesize speech from text (TTS).

**Request Body**:

```json
{
  "text": "Hello, welcome to LibreFang.",
  "voice": "alloy",
  "format": "mp3",
  "speed": 1.0
}
```

All fields except `text` are optional.

**Response** `200 OK`:

```json
{
  "url": "/api/uploads/550e8400-...",
  "format": "mp3",
  "provider": "openai",
  "model": "tts-1",
  "duration_ms": 2400,
  "sample_rate": 24000
}
```

### POST /api/media/video

Submit an asynchronous video generation task. Returns a task ID for polling.

**Request Body**:

```json
{
  "prompt": "A cat playing piano in a jazz bar",
  "provider": "minimax",
  "duration_secs": 5
}
```

All fields except `prompt` are optional.

**Response** `202 Accepted`:

```json
{
  "task_id": "task-abc123",
  "provider": "minimax"
}
```

### GET /api/media/video/&lbrace;task_id&rbrace;?provider=minimax

Poll video generation task status. The `provider` query parameter is required.

**Response** `200 OK` (in progress):

```json
{
  "status": "processing",
  "task_id": "task-abc123"
}
```

**Response** `200 OK` (completed):

```json
{
  "status": "completed",
  "result": {
    "file_url": "https://cdn.example.com/video.mp4",
    "width": 1280,
    "height": 720,
    "duration_secs": 5.0,
    "provider": "minimax",
    "model": "T2V-01"
  }
}
```

### POST /api/media/music

Generate music from a text prompt and/or lyrics.

**Request Body**:

```json
{
  "prompt": "Upbeat electronic dance track",
  "lyrics": "",
  "instrumental": true,
  "format": "mp3"
}
```

At least one of `prompt` or `lyrics` is required.

**Response** `200 OK`:

```json
{
  "url": "/api/uploads/550e8400-...",
  "format": "mp3",
  "duration_ms": 180000,
  "provider": "minimax",
  "model": "music-2.5",
  "sample_rate": 44100
}
```

### GET /api/media/providers

List available media providers with their capabilities and configuration status.

**Response** `200 OK`:

```json
{
  "providers": [
    {
      "name": "openai",
      "configured": true,
      "capabilities": ["ImageGeneration", "TextToSpeech"]
    },
    {
      "name": "minimax",
      "configured": true,
      "capabilities": ["ImageGeneration", "TextToSpeech", "VideoGeneration", "MusicGeneration"]
    }
  ]
}
```

---

