Skip to main content
List all memory documents with optional filtering by category, scope, or project.

​
Endpoint

GET /api/memory/list
Authentication: Required (Bearer token)

​
Query parameters

​
category
string
Filter by category. One of: preferences, decisions, patterns, context, learnings, general, gate-rules, guidelines
​
scope
string
default:"both"
Filter by scope:
  • personal - Only personal memories
  • shared - Only team-shared memories
  • both - Both scopes (default)
​
project
string
Filter by project. Format: org/repoReturns memories with source_ref matching project:org/repo
​
limit
integer
default:100
Maximum number of results to return
​
offset
integer
default:0
Number of results to skip (for pagination)
​
include_deleted
boolean
default:false
Whether to include soft-deleted memories

​
Response

​
success
boolean
Whether the operation succeeded
​
documents
object[]
Array of memory documents
​
count
integer
Number of documents returned
​
total
integer
Total number of matching documents (for pagination)

​
Examples

​
List all memories

curl -X GET "https://your-cems-server.com/api/memory/list" \
  -H "Authorization: Bearer $CEMS_API_KEY"

​
Filter by category

curl -X GET "https://your-cems-server.com/api/memory/list?category=preferences&limit=50" \
  -H "Authorization: Bearer $CEMS_API_KEY"

​
Filter by project

curl -X GET "https://your-cems-server.com/api/memory/list?project=acme/api-server" \
  -H "Authorization: Bearer $CEMS_API_KEY"

​
Pagination

# First page
curl -X GET "https://your-cems-server.com/api/memory/list?limit=50&offset=0" \
  -H "Authorization: Bearer $CEMS_API_KEY"

# Second page
curl -X GET "https://your-cems-server.com/api/memory/list?limit=50&offset=50" \
  -H "Authorization: Bearer $CEMS_API_KEY"
Response: 
{
  "success": true,
  "documents": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "I prefer using TypeScript for all new backend services",
      "category": "preferences",
      "scope": "personal",
      "source_ref": null,
      "tags": ["typescript", "backend"],
      "created_at": "2024-02-28T10:30:00Z",
      "is_pinned": false,
      "is_deleted": false
    }
  ],
  "count": 1,
  "total": 42
}

​
Use cases

  • Memory audit: Review all stored memories
  • Batch operations: Find memories to update or delete
  • Export: Export all memories for backup
  • Category management: See what’s in each category
  • Project context: List all memories for a specific project

​
Performance

  • The query uses database indexes for efficient filtering
  • Content is truncated to 500 characters in list view
  • Use pagination for large result sets
  • For searching by content, use Search memories instead

​
Error responses

Status codes:
  • 401 - Unauthorized (invalid or missing API key)
  • 500 - Internal server error

​
CLI equivalent

# List all memories
cems list

# Filter by category
cems list --category preferences

# Limit results
cems list --limit 50

Build docs developers (and LLMs) love

Get started for freeTalk to us