Tools

Available MCP Tools¶

create_collection¶

Creates a new collection to store memories.

Parameters: - collection_name (string, required): Collection name - description (string, optional): Collection description - vector_size (number, optional): Vector size (default: automatically detected)

Example:

curl -X POST "https://akashic-mcp.com/tools/call" \
  -H "Authorization: Bearer mcp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "create_collection",
    "arguments": {
      "collection_name": "my-memories",
      "description": "My personal memories"
    }
  }'

Nota: Autentica con MCP token (Bearer) u OAuth2.

list_collections¶

Lists all user collections.

Parameters: None

Example:

curl -X POST "https://akashic-mcp.com/tools/call" \
  -H "Authorization: Bearer mcp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "list_collections",
    "arguments": {}
  }'

memory (action: "get_context")¶

Returns the complete context needed to start an interaction: identity, the active conversation/case memory, related memories, and the do/dont sets. This is the recommended first call for every interaction, and is mandatory before any substantive work.

Parameters: - action (string, required): "get_context" - query (string, optional): Context query used to find related memories - project_name (string, optional): Project name (scopes case memory selection and enables project_rules retrieval) - project_id (string, optional): Project ID (alternative to project_name) - detected_identity (object, optional): Identity hints detected from system messages/context, passed before any IDENTITY memory exists

Response fields: - identity (object | null): the active IDENTITY memory (personality, nicknames, user address, emotional state), or null when no identity is configured. - conversation_memory_id (string | null): the most relevant active conversation/case memory ID (scoped to the project when project_name/project_id is provided), or null. Use this exact ID for memory action update on the same case. - related_memories (array): semantically related memories based on query. - get_context_do_dont (array): hardcoded workflow rules (unchanged). - general_do_dont (array): owner-wide do/dont preferences with no project scope (unchanged). - project_do_dont (array | null): legacy project-scoped short-form do/dont. Deprecated in favor of project_rules.do / project_rules.dont. - project_rules (object | absent): guaranteed project-scoped unified long-form rules. Returned only when project_name or project_id is provided. Fetched by direct filter (not semantic search), so it is always present and cannot be omitted by ranking or pagination. Shape:

"project_rules": {
  "do":   { "id": "...", "content": "...", "metadata": { "rule_type": "do", ... } } | null,
  "dont": { "id": "...", "content": "...", "metadata": { "rule_type": "dont", ... } } | null,
  "todo": { "id": "...", "content": "...", "metadata": { "rule_type": "todo", ... } } | null
}

Each entry is a single memory with event_type: "project-rule" and metadata.rule_type: "do" | "dont" | "todo". There is at most one memory per project per rule_type (no fragmentation). The todo variant is a structured SDD document with markdown sections ## Constitution, ## Spec, ## Plan, ## Tasks, ## Gaps. Store them via the rules tool (do/dont) and the todo tool (todo).

Example:

curl -X POST "https://akashic-mcp.com/tools/call" \
  -H "Authorization: Bearer mcp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "memory",
    "arguments": {
      "action": "get_context",
      "query": "Current request context",
      "project_name": "my-api"
    }
  }'

memory (action: "store")¶

Stores a new memory in a collection.

Parameters: - action (string, required): "store" - collection_name (string, optional): Collection name - content (string, required): Memory content - metadata (object, optional): Additional metadata - event_type (string): Type of event (e.g., "project-main", "conversation", "decision") - state (string): State (e.g., "active", "archived", "completed") - project_name (string): Project name - project_id (string): Project ID - importance (string): Importance level ("low", "medium", "high", "critical") - classification (string, optional): Classification ("do", "dont", "todo", "notes") - tags (array, optional): Tags for searchability - related_memory_ids (array, optional): Related memory IDs

Example:

curl -X POST "https://akashic-mcp.com/tools/call" \
  -H "Authorization: Bearer mcp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "memory",
    "arguments": {
      "action": "store",
      "content": "The user prefers TypeScript over JavaScript",
      "metadata": {
        "category": "preferences",
        "timestamp": "2024-01-15T10:00:00Z"
      },
      "classification": "notes",
      "tags": ["preferences", "typescript"]
    }
  }'

memory (action: "search")¶

Searches memories using semantic search with optional filters, pagination and sorting.

Parameters: - action (string, required): "search" - collection_name (string, optional): Collection name (searches all if omitted) - query (string, optional): Search text (or use query_embedding) - query_embedding (array, optional): Embedding vector for search - limit (number, optional): Maximum number of results per page (default: 7) - offset (number, optional): Index of the first result to return (default: 0). Use with limit for pagination. - sort_order (string, optional): Sort order (default: "relevance"). Values: "relevance", "updated_at_asc", "updated_at_desc", "created_at_asc", "created_at_desc". - classification (string, optional): Filter by classification ("do", "dont", "todo", "notes") - tags (array, optional): Filter by tags - include_files (boolean, optional): Include files in results (default: false) - filter (object, optional): Additional filters (project_name, project_id, event_type, etc.)

Response always includes offset, limit, and sort_order for pagination.

Response includes files array for each memory:

{
  "results": [
    {
      "collection_name": "my-memories",
      "memories": [
        {
          "id": "mem-123",
          "content": "...",
          "files": [
            {
              "id": "file-123",
              "filename": "documentation.pdf",
              "mime_type": "application/pdf",
              "size": 1024000
            }
          ]
        }
      ]
    }
  ]
}

Example:

curl -X POST "https://akashic-mcp.com/tools/call" \
  -H "Authorization: Bearer mcp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "memory",
    "arguments": {
      "action": "search",
      "query": "development preferences",
      "limit": 5,
      "include_files": true
    }
  }'

memory (action: "retrieve")¶

Retrieves a specific memory by ID and includes linked files.

Parameters: - action (string, required): "retrieve" - id (string, required): Memory ID - collection_name (string, optional): Collection name (searches all if omitted)

Behavior verified in code: - If collection_name is omitted, the server searches across accessible collections. - For shared projects, fallback lookup also checks collections of shared project owners.

Response includes files array:

{
  "result": "Memory ID: mem-123\nContent: ...\nFiles (2):\n  - documentation.pdf\n  - diagram.png",
  "memory": {
    "id": "mem-123",
    "content": "...",
    "collection_name": "my-memories"
  },
  "files": [
    {
      "id": "file-123",
      "filename": "documentation.pdf",
      "mime_type": "application/pdf",
      "size": 1024000
    }
  ]
}

Example:

curl -X POST "https://akashic-mcp.com/tools/call" \
  -H "Authorization: Bearer mcp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "memory",
    "arguments": {
      "action": "retrieve",
      "id": "mem-123",
      "collection_name": "my-memories"
    }
  }'

memory (action: "update")¶

Updates an existing memory by ID.

Parameters: - action (string, required): "update" - id (string, required): Memory ID - collection_name (string, optional): Collection name - content (string, optional): New content - metadata (object, optional): New metadata

Example:

curl -X POST "https://akashic-mcp.com/tools/call" \
  -H "Authorization: Bearer mcp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "memory",
    "arguments": {
      "action": "update",
      "id": "mem-123",
      "content": "Updated content"
    }
  }'

memory (action: "delete")¶

Deletes a memory by ID.

Parameters: - action (string, required): "delete" - id (string, required): Memory ID - collection_name (string, optional): Collection name

Example:

curl -X POST "https://akashic-mcp.com/tools/call" \
  -H "Authorization: Bearer mcp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "memory",
    "arguments": {
      "action": "delete",
      "id": "mem-123"
    }
  }'

rules¶

Stores and retrieves project-scoped long-form do/dont rules. Project rules are memories with event_type: "project-rule" and metadata.rule_type: "do" | "dont". There is at most one memory per project per rule_type (no fragmentation); storing when one already exists performs an upsert on the single existing memory.

Actions:

rules (action: "store")¶

Stores (upserts) a project-scoped long-form do/dont rule.

Parameters: - action (string, required): "store" - project_name (string, optional): Project name (one of project_name/project_id required for project-scoped rules) - project_id (string, optional): Project ID - rule_type (string, required): "do" | "dont" - content (string, required): Long-form markdown content of the rule - tags (array, optional): Tags for searchability - related_memory_ids (array, optional): Related memory IDs

When project_name/project_id is omitted, the existing owner-wide general do/dont behavior (general_do_dont) is unchanged.

Example:

curl -X POST "https://akashic-mcp.com/tools/call" \
  -H "Authorization: Bearer mcp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "rules",
    "arguments": {
      "action": "store",
      "project_name": "my-api",
      "rule_type": "dont",
      "content": "# Project dont\\n- Never use setTimeout/setInterval in the codebase\\n- Do not commit secrets to git",
      "tags": ["coding-standards", "anti-patterns"]
    }
  }'

todo¶

Stores and evolves the project-scoped Spec-Driven Development (SDD) document as a single project-rule memory with metadata.rule_type: "todo". The content is long-form markdown with sections ## Constitution, ## Spec, ## Plan, ## Tasks, ## Gaps. This replaces spec-kit filesystem artifacts (spec.md, plan.md, tasks.md, constitution.md) as the canonical SDD store. There is at most one todo memory per project; storing when one already exists performs an upsert.

Actions:

todo (action: "store")¶

Stores (upserts) the project todo memory with the full SDD content.

Parameters: - action (string, required): "store" - project_name (string, optional): Project name (one of project_name/project_id required) - project_id (string, optional): Project ID - content (string, required): Full SDD markdown content with the five sections - tags (array, optional): Tags for searchability - related_memory_ids (array, optional): Related memory IDs

todo (action: "update_section")¶

Replaces a single markdown section of the project todo memory, preserving the other sections.

Parameters: - action (string, required): "update_section" - project_name (string, optional): Project name (one of project_name/project_id required) - project_id (string, optional): Project ID - section (string, required): "constitution" | "spec" | "plan" | "tasks" | "gaps" - content (string, required): New markdown content for that section (without the ## heading duplication; the section heading is preserved)

todo (action: "complete")¶

Project-scoped task completion: flips - [ ] T00X → - [x] T00X inside the ## Tasks section of the project todo memory.

Parameters: - action (string, required): "complete" - project_name (string, optional): Project name (one of project_name/project_id required) - project_id (string, optional): Project ID - task_id (string, required): Task identifier as written in ## Tasks, e.g. "T003"

Example (store the SDD document):

curl -X POST "https://akashic-mcp.com/tools/call" \
  -H "Authorization: Bearer mcp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "todo",
    "arguments": {
      "action": "store",
      "project_name": "my-api",
      "content": "## Constitution\\n...\\n## Spec\\n...\\n## Plan\\n...\\n## Tasks\\n- [ ] T001 Create project structure per implementation plan\\n- [ ] T002 [P] Implement auth middleware in src/middleware/auth.py\\n## Gaps\\n..."
    }
  }'

Example (complete a task):

curl -X POST "https://akashic-mcp.com/tools/call" \
  -H "Authorization: Bearer mcp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "todo",
    "arguments": {
      "action": "complete",
      "project_name": "my-api",
      "task_id": "T001"
    }
  }'

get_project_main_memory¶

Retrieves the main memory of a project. This should be the FIRST tool called when working on a project.

Parameters: - project_name (string, optional): Project name (either project_name or project_id required) - project_id (string, optional): Project ID (either project_name or project_id required)

Response includes: - Main memory content and metadata - All files linked to the main memory - Related memories (up to 2 levels deep)

Example:

curl -X POST "https://akashic-mcp.com/tools/call" \
  -H "Authorization: Bearer mcp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_project_main_memory",
    "arguments": {
      "project_name": "my-api"
    }
  }'

get_module_state¶

Consults the current state of a module/component. Returns all memories and files related to the module.

Parameters: - module_name (string, required): Module name (e.g., "authentication", "database") - project_name (string, optional): Filter by project name - project_id (string, optional): Filter by project ID - limit (number, optional): Maximum results (default: 10)

Response includes: - All memories related to the module - All files linked to those memories - Summary of findings

Example:

curl -X POST "https://akashic-mcp.com/tools/call" \
  -H "Authorization: Bearer mcp_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_module_state",
    "arguments": {
      "module_name": "authentication",
      "project_name": "my-api"
    }
  }'

API Reference - Complete API reference
Getting Started - Quick start guide

Tools

Available MCP Tools¶

create_collection¶

list_collections¶

memory (action: "get_context")¶

memory (action: "store")¶

memory (action: "search")¶

memory (action: "retrieve")¶

memory (action: "update")¶

memory (action: "delete")¶

rules¶

rules (action: "store")¶

todo¶

todo (action: "store")¶

todo (action: "update_section")¶

todo (action: "complete")¶

get_project_main_memory¶

get_module_state¶

Related Documentation¶