Skip to content

API Reference

Jump to bottom
Zhafron Kautsar edited this page Jan 12, 2026 · 1 revision

API Reference

Complete reference for OpenCode Memory tool and REST API.

Memory Tool

The memory tool provides access to all memory operations from within AI conversations.

Tool Syntax

memory({ mode: string, ...args })

Modes

add

Store a new project memory.

Parameters:

  • content (string, required): Memory content
  • type (string, optional): Memory type (e.g., "preference", "architecture", "bug-fix")

Example:

memory({
  mode: "add",
  content: "Project uses microservices architecture with Docker",
  type: "architecture"
})

Response:

{
  "success": true,
  "message": "Memory added to project",
  "id": "mem_1234567890_abc",
  "type": "architecture"
}

search

Search for relevant memories using vector similarity.

Parameters:

  • query (string, required): Search query

Example:

memory({
  mode: "search",
  query: "architecture decisions"
})

Response:

{
  "success": true,
  "query": "architecture decisions",
  "count": 3,
  "results": [
    {
      "id": "mem_1234567890_abc",
      "content": "Project uses microservices architecture",
      "similarity": 87
    }
  ]
}

list

List recent memories.

Parameters:

  • limit (number, optional): Maximum number of results (default: 20)

Example:

memory({
  mode: "list",
  limit: 10
})

Response:

{
  "success": true,
  "count": 10,
  "memories": [
    {
      "id": "mem_1234567890_abc",
      "content": "Project uses microservices architecture",
      "createdAt": "2026-01-12T10:30:00.000Z",
      "metadata": { "type": "architecture" }
    }
  ]
}

profile

View user profile with preferences, patterns, workflows, and skill assessment.

Parameters: None

Example:

memory({ mode: "profile" })

Response:

{
  "success": true,
  "profile": {
    "preferences": [
      {
        "category": "code-style",
        "description": "Prefers functional programming",
        "confidence": 0.85,
        "evidence": ["Consistently uses pure functions", "Avoids mutations"]
      }
    ],
    "patterns": [
      {
        "category": "problem-domain",
        "description": "Frequently works on API design",
        "frequency": 15
      }
    ],
    "workflows": [
      {
        "description": "Writes tests before implementation",
        "frequency": 8
      }
    ],
    "skillLevel": {
      "overall": "advanced",
      "domains": {
        "typescript": "expert",
        "react": "advanced"
      }
    },
    "version": 3,
    "lastAnalyzed": "2026-01-12T10:00:00.000Z",
    "totalPromptsAnalyzed": 150
  }
}

forget

Delete a memory by ID.

Parameters:

  • memoryId (string, required): Memory ID to delete

Example:

memory({
  mode: "forget",
  memoryId: "mem_1234567890_abc"
})

Response:

{
  "success": true,
  "message": "Memory mem_1234567890_abc removed"
}

capture-now

Manually trigger memory capture for the current session.

Parameters: None

Example:

memory({ mode: "capture-now" })

Response:

{
  "success": true,
  "message": "Manual capture triggered"
}

help

Display usage guide.

Parameters: None

Example:

memory({ mode: "help" })

REST API

The web server provides a REST API for memory management.

Base URL: http://127.0.0.1:4747

Memory Endpoints

GET /api/memories

List memories with optional filters.

Query Parameters:

  • page (number): Page number (default: 1)
  • pageSize (number): Items per page (default: 20)
  • tag (string): Filter by tag
  • includePrompts (boolean): Include linked prompts (default: true)

Example:

curl http://127.0.0.1:4747/api/memories?page=1&pageSize=20&includePrompts=true

Response:

{
  "success": true,
  "data": {
    "items": [...],
    "total": 50,
    "page": 1,
    "pageSize": 20,
    "totalPages": 3
  }
}

POST /api/memories

Create a new memory.

Body:

{
  "content": "Memory content",
  "containerTag": "opencode_project_abc123",
  "type": "architecture"
}

Response:

{
  "success": true,
  "data": {
    "id": "mem_1234567890_abc"
  }
}

PUT /api/memories/:id

Update a memory.

Body:

{
  "content": "Updated content",
  "type": "architecture"
}

Response:

{
  "success": true,
  "data": {
    "id": "mem_1234567890_abc"
  }
}

DELETE /api/memories/:id

Delete a memory.

Query Parameters:

  • cascade (boolean): Also delete linked prompt (default: false)

Example:

curl -X DELETE http://127.0.0.1:4747/api/memories/mem_1234567890_abc?cascade=true

Response:

{
  "success": true,
  "data": {
    "deletedPrompt": true
  }
}

POST /api/search

Search memories using vector similarity.

Body:

{
  "query": "architecture decisions",
  "page": 1,
  "pageSize": 10
}

Response:

{
  "success": true,
  "data": {
    "items": [...],
    "total": 5,
    "page": 1,
    "pageSize": 10,
    "totalPages": 1
  }
}

Prompt Endpoints

DELETE /api/prompts/:id

Delete a prompt.

Query Parameters:

  • cascade (boolean): Also delete linked memory (default: false)

Example:

curl -X DELETE http://127.0.0.1:4747/api/prompts/prompt_1234567890_abc?cascade=true

User Profile Endpoints

GET /api/profile

Get user profile.

Response:

{
  "success": true,
  "profile": {
    "preferences": [...],
    "patterns": [...],
    "workflows": [...],
    "skillLevel": {...},
    "version": 3,
    "lastAnalyzed": "2026-01-12T10:00:00.000Z"
  }
}

GET /api/profile/changelog

Get profile changelog.

Query Parameters:

  • limit (number): Maximum entries (default: 10)

Response:

{
  "success": true,
  "changelog": [
    {
      "id": 1,
      "version": 3,
      "changedAt": "2026-01-12T10:00:00.000Z",
      "changes": "Added 2 new preferences, updated 1 pattern"
    }
  ]
}

GET /api/profile/snapshot/:changelogId

Get profile snapshot from changelog.

Response:

{
  "success": true,
  "snapshot": {
    "preferences": [...],
    "patterns": [...],
    "workflows": [...],
    "skillLevel": {...}
  }
}

POST /api/profile/refresh

Force profile refresh/analysis.

Response:

{
  "success": true,
  "message": "Profile refresh triggered"
}

Maintenance Endpoints

GET /api/tags

List all tags.

Response:

{
  "success": true,
  "data": {
    "project": [
      {
        "tag": "opencode_project_abc123",
        "displayName": "my-project",
        "projectPath": "/home/user/projects/my-project"
      }
    ]
  }
}

GET /api/stats

Get memory statistics.

Response:

{
  "success": true,
  "data": {
    "total": 150
  }
}

POST /api/cleanup

Run memory cleanup (delete old memories).

Response:

{
  "success": true,
  "data": {
    "deletedCount": 10
  }
}

POST /api/deduplicate

Run deduplication (remove similar memories).

Response:

{
  "success": true,
  "data": {
    "duplicatesFound": 5,
    "duplicatesRemoved": 5
  }
}

Error Responses

All endpoints return errors in this format:

{
  "success": false,
  "error": "Error message"
}

Common HTTP status codes:

  • 200: Success
  • 400: Bad request (invalid parameters)
  • 404: Not found
  • 500: Internal server error

Notes

  • All memories are project-scoped by default
  • User preferences are managed through the automatic profile system
  • Memory IDs are unique and persistent
  • Timestamps are in ISO 8601 format
  • Similarity scores are percentages (0-100)

Clone this wiki locally