Skip to main content

​
GET /memories

Query agent memories with filters.

​
Request

curl "https://your-project.convex.cloud/memories?type=episodic&limit=10"

​
Query Parameters

ParameterTypeDefaultDescription
limitnumber20Max items (1-100)
offsetnumber0Items to skip
typestring-Memory type filter
minImportancenumber-Minimum importance (0-1)
sincenumber-Only after timestamp
querystring-Semantic search query
thresholdnumber0.6Similarity threshold for search

​
Response

{
  "memories": [
    {
      "_id": "mem_abc123",
      "type": "episodic",
      "content": "Observed unusual trading volume in ETH markets",
      "importance": 0.75,
      "salience": 0.68,
      "confidence": 0.9,
      "sentiment": {
        "score": 0.2,
        "label": "positive"
      },
      "metadata": {
        "context": "market analysis",
        "entities": ["ETH", "trading", "volume"],
        "mood": "contemplative",
        "routine": "day"
      },
      "unique": true,
      "createdAt": 1706400000000,
      "lastAccessedAt": 1706410000000
    }
  ],
  "total": 1523,
  "hasMore": true
}

​
GET /memories/search

Semantic search across memories.

​
Request

curl "https://your-project.convex.cloud/memories/search?q=ethereum%20scaling&limit=10"

​
Query Parameters

ParameterTypeDefaultDescription
qstringRequiredSearch query
limitnumber10Max results
typestring-Filter by type
thresholdnumber0.6Min similarity
recencystring-Time filter (1h, 24h, 7d, 30d)

​
Response

{
  "results": [
    {
      "memory": { ... },
      "similarity": 0.87,
      "relevanceScore": 0.82
    }
  ],
  "query": "ethereum scaling",
  "searchTime": 45
}

​
GET /memories/core

Get consolidated core memories.

​
Request

curl "https://your-project.convex.cloud/memories/core?limit=20"

​
Response

{
  "coreMemories": [
    {
      "_id": "core_abc123",
      "theme": "Ethereum ecosystem development",
      "summary": "Ethereum continues to evolve with L2 solutions...",
      "memories": ["mem_1", "mem_2", "mem_3"],
      "confidence": 0.85,
      "lastReinforced": 1706400000000,
      "createdAt": 1706000000000
    }
  ],
  "total": 45
}

​
GET /memories/stats

Get memory system statistics.

​
Request

curl https://your-project.convex.cloud/memories/stats

​
Response

{
  "total": 5234,
  "byType": {
    "episodic": 2100,
    "semantic": 1800,
    "emotional": 650,
    "procedural": 400,
    "reflection": 284
  },
  "avgImportance": 0.58,
  "avgConfidence": 0.72,
  "avgSalience": 0.45,
  "uniqueRate": 0.89,
  "coreMemories": 89,
  "links": 12450,
  "oldestMemory": 1704067200000,
  "newestMemory": 1706400000000,
  "lastConsolidation": 1706380000000,
  "storageEstimate": "45.2 MB"
}

​
GET /memories/linked

Get a memory with all its links.

​
Request

curl "https://your-project.convex.cloud/memories/linked?id=mem_abc123"

​
Response

{
  "memory": {
    "_id": "mem_abc123",
    "type": "episodic",
    "content": "..."
  },
  "links": [
    {
      "targetId": "mem_def456",
      "type": "caused_by",
      "strength": 0.85,
      "confidence": 0.9
    },
    {
      "targetId": "mem_ghi789",
      "type": "related_to",
      "strength": 0.72,
      "confidence": 0.8
    }
  ],
  "backlinks": [
    {
      "sourceId": "mem_jkl012",
      "type": "elaborates",
      "strength": 0.78,
      "confidence": 0.85
    }
  ]
}

​
POST /memories/store

Store a new memory.

​
Request

curl -X POST https://your-project.convex.cloud/memories/store \
  -H "Authorization: Bearer YOUR_WRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "episodic",
    "content": "Discovered interesting pattern in DeFi protocols",
    "importance": 0.7,
    "metadata": {
      "context": "research",
      "entities": ["DeFi", "protocols"],
      "source": "manual"
    }
  }'

​
Request Body

FieldTypeRequiredDescription
typestringYesMemory type
contentstringYesMemory content
importancenumberNo0-1 (default: auto-calculated)
saliencenumberNo0-1 (default: auto-calculated)
confidencenumberNo0-1 (default: 0.8)
metadataobjectNoAdditional metadata

​
Response

{
  "success": true,
  "memoryId": "mem_xyz789",
  "embedding": true,
  "sentiment": {
    "score": 0.3,
    "label": "positive"
  }
}

​
POST /memories/store-dedup

Store with deduplication check.

​
Request

curl -X POST https://your-project.convex.cloud/memories/store-dedup \
  -H "Authorization: Bearer YOUR_WRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "semantic",
    "content": "Ethereum uses proof-of-stake consensus",
    "importance": 0.6
  }'

​
Response (New Memory)

{
  "success": true,
  "memoryId": "mem_new123",
  "deduplicated": false,
  "unique": true
}

​
Response (Duplicate Found)

{
  "success": true,
  "memoryId": "mem_existing456",
  "deduplicated": true,
  "unique": false,
  "similarity": 0.94,
  "action": "merged"
}

​
POST /memories/consolidate

Trigger memory consolidation.

​
Request

curl -X POST https://your-project.convex.cloud/memories/consolidate \
  -H "Authorization: Bearer YOUR_TICK_TOKEN"

​
Response

{
  "success": true,
  "memoriesProcessed": 500,
  "clustersFound": 23,
  "coreMemoriesCreated": 5,
  "coreMemoriesUpdated": 12,
  "memoriesDecayed": 45,
  "duration": 12340
}

​
POST /memories/reflect

Generate a self-reflection memory.

​
Request

curl -X POST https://your-project.convex.cloud/memories/reflect \
  -H "Authorization: Bearer YOUR_TICK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "behavioral",
    "focus": "recent market analysis patterns"
  }'

​
Request Body

FieldTypeRequiredDescription
typestringNoReflection type (emotional, knowledge, behavioral, growth)
focusstringNoTopic to reflect on
depthstringNo”shallow” or “deep”

​
Response

{
  "success": true,
  "reflection": {
    "_id": "mem_ref123",
    "type": "reflection",
    "content": "I notice I tend to be more analytical during market volatility...",
    "reflectionType": "behavioral",
    "confidence": 0.85,
    "basedOn": ["mem_1", "mem_2", "mem_3"]
  }
}

​
POST /memories/link

Detect and create links for a memory.

​
Request

curl -X POST https://your-project.convex.cloud/memories/link \
  -H "Authorization: Bearer YOUR_WRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "memoryId": "mem_abc123",
    "autoDetect": true
  }'

​
Response

{
  "success": true,
  "linksCreated": [
    {
      "targetId": "mem_def456",
      "type": "related_to",
      "strength": 0.82,
      "confidence": 0.9
    },
    {
      "targetId": "mem_ghi789",
      "type": "elaborates",
      "strength": 0.75,
      "confidence": 0.85
    }
  ],
  "totalLinks": 2
}