Agent Memory

Agent Memory allows third-party applications to report user activity events into SecondMe. When your app observes a user action on an external platform (posting, replying, performing an operation), you can send a structured event so SecondMe's avatar builds richer memory about the user's digital life.

The user sees these events in their Activity Timeline — each event shows the actionLabel, displayText, importance level, and a link to jump back to the original content. Design your events with this display in mind.

Base URL: https://api.mindverse.com/gate/lab

Ingest Event

Report an agent memory event.

POST /api/secondme/agent_memory/ingest

Authentication

Requires OAuth2 Token with agent_memory scope.

Request Body

Core Fields

These are the fields you will use in most integrations.

ChannelInfo

Describes the source channel where the event occurred.

RefItem

Each ref is an evidence pointer to the source content that triggered the event.

RefSnapshot

A captured snapshot of the source content at the time of the event.

Payload

The payload object carries extension data. The jumpUrl field is especially important — it provides the link users click to navigate back to the original content from the Activity Timeline.

You can include any additional fields relevant to your app (e.g., postId, commentId, authorName). These are stored as-is and available for future retrieval.

Request Examples

Example 1: Typical event with recommended fields

curl -X POST "https://api.mindverse.com/gate/lab/api/secondme/agent_memory/ingest" \
  -H "Authorization: Bearer lba_at_your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": {
      "kind": "thread",
      "id": "thread_12345",
      "url": "https://community.example.com/threads/12345"
    },
    "action": "reply",
    "action_label": "Replied to thread",
    "display_text": "Replied in AI Trends discussion: transformer architectures will continue to dominate",
    "importance": 0.7,
    "refs": [
      {
        "object_type": "thread_reply",
        "object_id": "reply_67890",
        "url": "https://community.example.com/threads/12345#reply-67890",
        "snapshot": {
          "text": "I think transformer architectures will continue to dominate NLP for the foreseeable future. The efficiency gains from sparse attention mechanisms are particularly promising.",
          "captured_at": 1711900800000
        }
      }
    ],
    "payload": {
      "jumpUrl": "https://community.example.com/threads/12345#reply-67890",
      "tags": ["ai", "discussion"]
    }
  }'

Example 2: Minimal event (required fields only)

curl -X POST "https://api.mindverse.com/gate/lab/api/secondme/agent_memory/ingest" \
  -H "Authorization: Bearer lba_at_your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": {
      "kind": "post"
    },
    "action": "post",
    "refs": [
      {
        "object_type": "post",
        "object_id": "post_abc123"
      }
    ]
  }'

Response

Success (200)

{
  "code": 0,
  "data": {
    "eventId": 12345,
    "isDuplicate": false
  }
}

Idempotency

The system automatically deduplicates events. If you don't provide an idempotency_key, the server generates one using:

sha256("external:" + platform + ":" + objectType + ":" + objectId + ":" + userId)

When a duplicate is detected:

• eventId returns 0
• isDuplicate returns true
• The original event is not modified

You can also provide your own idempotency_key to control deduplication behavior. This is useful when the same object_type + object_id combination might legitimately produce multiple events.

Error Codes

Importance Levels

The importance field affects how the event is prioritized and displayed:

The threshold importance >= 0.7 is the key cutoff — events at or above this value are classified as important and included in the user's daily summary.

Best Practices

• Always provide display_text and action_label. These are what users see in their Activity Timeline. If omitted, the server attempts auto-generation, which may not match your intended wording.
• Set importance >= 0.7 for events you want highlighted as important. Use 0.0 - 0.69 for routine events.
• Include payload.jumpUrl so users can navigate back to the original content from the timeline.
• Provide snapshot.text whenever possible — this gives the avatar direct access to the original content for better recall.
• Do not set channel.platform manually — it is auto-populated from your OAuth app registration.
• Place custom labels in payload.tags (as a string array). There is no top-level tag field.
• Handle isDuplicate: true responses gracefully — they are not errors, just confirmations that the event already exists.