Tools Reference

The hosted memories.sh MCP endpoint exposes 9 tenant-routed core tools. The local CLI MCP server (memories serve) extends that surface with 5 lifecycle tools, 6 reminder tools, and 4 streaming tools.

Scope model for MCP arguments:

• tenant_id = AI SDK Project (security/database boundary)
• user_id = end-user scope inside tenant_id
• project_id = optional repo context filter (not auth boundary)

Availability notes:

• Hosted MCP (https://memories.sh/api/mcp) supports the tenant-routed core toolset documented here.
• Local CLI MCP (memories serve) includes additional lifecycle, reminder, and streaming tools.

get_context

The primary tool for AI agents. Returns all active rules (with path and category metadata) plus memories relevant to an optional search query.

{
  "name": "get_context",
  "arguments": {
    "query": "authentication flow",
    "project_id": "github.com/user/repo",
    "limit": 5
  }
}

Returns all rules first (including path scope and category when set), followed by relevant search results. Uses FTS5 with BM25 ranking for the search query, falling back to LIKE matching for databases without FTS support. When hybrid graph retrieval is enabled, semantically similar memories may be added via graph similar_to edges, and conflict/refinement links may be traversed via contradicts / supersedes edges when LLM extraction is enabled.

When local memories serve callers provide session_id and compaction hints (budget_tokens, turn_budget/turn_count, inactivity fields, or task_completed), get_context may emit a compaction section and perform write-ahead checkpointing before destructive compaction.

If returned memories include contradiction links, the response also includes a conflicts[] array with pair IDs, confidence, explanation text, and a suggestion for clarification.

Example structuredContent conflict payload fragment:

{
  "data": {
    "memories": [
      { "id": "mem_a", "content": "I prefer tea in the afternoon." },
      { "id": "mem_b", "content": "I avoid tea after lunch." }
    ],
    "conflicts": [
      {
        "memoryAId": "mem_a",
        "memoryBId": "mem_b",
        "edgeType": "contradicts",
        "confidence": 0.88,
        "explanation": "These memories are linked by a contradiction edge from relationship extraction.",
        "suggestion": "These memories may conflict. Consider asking the user to clarify which preference is current."
      }
    ],
    "trace": {
      "strategy": "hybrid_graph",
      "conflictCount": 1
    }
  }
}

start_session (local CLI only)

Start a new session for checkpointing and snapshot workflows.

{
  "name": "start_session",
  "arguments": {
    "title": "Refactor auth middleware",
    "client": "codex",
    "project_id": "github.com/webrenew/memories"
  }
}

checkpoint_session (local CLI only)

Append an event/checkpoint to an active session.

{
  "name": "checkpoint_session",
  "arguments": {
    "session_id": "sess_123",
    "content": "User approved migration strategy",
    "kind": "summary",
    "token_count": 320
  }
}

end_session (local CLI only)

Close a session when task context is complete.

{
  "name": "end_session",
  "arguments": {
    "session_id": "sess_123",
    "status": "compacted"
  }
}

snapshot_session (local CLI only)

Create a raw markdown snapshot from explicit transcript text or recent session events.

{
  "name": "snapshot_session",
  "arguments": {
    "session_id": "sess_123",
    "source_trigger": "reset",
    "message_count": 15
  }
}

consolidate_memories (local CLI only)

Run consolidation to merge duplicates, supersede stale truths, and write consolidation audit rows.

{
  "name": "consolidate_memories",
  "arguments": {
    "types": ["rule", "decision", "fact"],
    "project_id": "github.com/webrenew/memories",
    "dry_run": true
  }
}

add_memory

Store a new memory with optional metadata, path scoping, and categorization.

{
  "name": "add_memory",
  "arguments": {
    "content": "Use RESTful naming conventions for all endpoints",
    "type": "rule",
    "paths": ["src/api/**", "src/routes/**"],
    "category": "api"
  }
}

Adding a skill:

{
  "name": "add_memory",
  "arguments": {
    "content": "## Deploy\n\n1. Run tests\n2. Build\n3. Deploy to production",
    "type": "skill",
    "category": "deploy",
    "metadata": {
      "name": "deploy",
      "description": "Deploy the application to production"
    }
  }
}

search_memories

Full-text search across memories with BM25 ranking. Uses FTS5 when available, falling back to LIKE matching.

{
  "name": "search_memories",
  "arguments": {
    "query": "database schema",
    "project_id": "github.com/user/repo",
    "type": "decision"
  }
}

get_rules

Get all active rules, split by global and project scope.

{
  "name": "get_rules",
  "arguments": {
    "project_id": "github.com/user/repo"
  }
}

list_memories

List recent memories with optional filters.

edit_memory

Update an existing memory's content, type, tags, path scope, or category.

{
  "name": "edit_memory",
  "arguments": {
    "id": "abc123def456",
    "paths": ["src/api/**"],
    "category": "api"
  }
}

forget_memory

Soft-delete a memory by ID.

bulk_forget_memories

Bulk soft-delete memories matching filters. Use dry_run: true to preview what would be deleted before committing.

Provide at least one filter (types, tags, older_than_days, or pattern), or use all: true. The all flag cannot be combined with other filters.

{
  "name": "bulk_forget_memories",
  "arguments": {
    "types": ["note", "fact"],
    "older_than_days": 90,
    "dry_run": true
  }
}

With dry_run: true, returns a preview with count and memories[] (each with id, type, contentPreview). With dry_run: false, returns count and ids[] of deleted memories. Deletes are batched in groups of 500.

vacuum_memories

Permanently purge all soft-deleted memories to reclaim storage space. This hard-deletes every row where deleted_at IS NOT NULL.

{
  "name": "vacuum_memories",
  "arguments": {}
}

Returns purged (count of permanently removed records) and a message string.

Local CLI Reminder Tools

add_reminder

Create a cron-based reminder.

list_reminders

List reminders in current scope.

run_due_reminders

Evaluate and emit due reminders.

enable_reminder

Enable a reminder and recompute next_trigger_at.

disable_reminder

Disable a reminder without deleting it.

delete_reminder

Delete a reminder by ID.

Local CLI Streaming Tools

start_memory_stream

Start a stream collector for chunked content.

append_memory_chunk

Append a chunk to an active stream.

finalize_memory_stream

Finalize stream and create the memory.

cancel_memory_stream

Cancel stream and discard buffered chunks.