API reference

Groups

Group graphs hold shared knowledge that doesn't belong to a single user. Same storage shape as user graphs — only the addressing differs.

When to use a group

User graphs hold facts about a person. Group graphs hold facts about the world — your product, your policies, your team's playbook. The same memory can be retrieved alongside a user's personal memories at search time, by passing both users and groups in the search request.

Default group

Every new project bootstraps with a default group graph. Ingest calls without an explicit group or userId land here. You can't delete it — it's the fallback target.

POST/v1/groups

Create a named group graph in the authenticated project.

Request

interface CreateGroupRequest {
  name: string;        // lowercase alphanumeric + - or _, max 64 chars
  description?: string;
}

Response (201)

{
  "id": "grph_01HXY...",
  "name": "policies",
  "description": "Company policy and benefits docs.",
  "createdAt": "2026-05-17T12:00:00Z"
}

Curl

curl -X POST "$MEMOS_URL/v1/groups" \
  -H "Authorization: Bearer $MEMOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "policies", "description": "Company handbook + benefits." }'

Creating a group with a name that already exists returns 409 with codeGROUP_EXISTS.

GET/v1/groups

List every group graph in the project.

{
  "groups": [
    {
      "id": "grph_...",
      "name": "default",
      "description": null,
      "createdAt": "...",
      "stats": { "memories": 142, "entities": 88 }
    },
    {
      "id": "grph_...",
      "name": "policies",
      "description": "...",
      "createdAt": "...",
      "stats": { "memories": 31, "entities": 12 }
    }
  ]
}

GET/v1/groups/:name

Get one group with detailed stats.

{
  "id": "grph_...",
  "name": "policies",
  "description": "Company handbook + benefits.",
  "createdAt": "...",
  "stats": {
    "memories": 31,
    "entities": 12,
    "ingestionJobs": 8
  }
}

DELETE/v1/groups/:name

Delete a group + cascade every memory, entity, and edge it holds. Thedefault group cannot be deleted via this endpoint.

{ "deleted": true, "name": "policies" }

Targeting a group on ingest

curl -X POST "$MEMOS_URL/v1/memory/add" \
  -H "Authorization: Bearer $MEMOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "All employees get 21 days of paid leave per year.",
    "group": "policies"
  }'

Multi-graph search

Search composes across user + group graphs additively. Use["*"] in groups to scan every group graph in the project at once:

curl -X POST "$MEMOS_URL/v1/memory/search" \
  -H "Authorization: Bearer $MEMOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "How many leave days do I have?",
    "projectTags": ["hr-bot"],
    "users":  ["user_clerk_abc"],
    "groups": ["policies"]
  }'

Next steps