---
title: "Add Memory V1"
method: POST
path: "/v1/memory"
tags: ["v1", "Memory"]
---

# Add Memory V1

`POST /v1/memory`

Add a new memory item to the system with size validation and background processing.
    
    **Authentication Required**:
    One of the following authentication methods must be used:
    - Bearer token in `Authorization` header
    - API Key in `X-API-Key` header
    - Session token in `X-Session-Token` header
    
    **Required Headers**:
    - Content-Type: application/json
    - X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')
    
    **Role-Based Memory Categories**:
    - **User memories**: preference, task, goal, facts, context
    - **Assistant memories**: skills, learning
    
    **New Metadata Fields**:
    - `metadata.role`: Optional field to specify who generated the memory (user or assistant)
    - `metadata.category`: Optional field for memory categorization based on role
    - Both fields are stored within metadata at the same level as topics, location, etc.
    
    The API validates content size against MAX_CONTENT_LENGTH environment variable (defaults to 15000 bytes).

## Query parameters

- `skip_background_processing` boolean — If True, skips adding background tasks for processing

## Request body

- AddMemoryRequest — Request model for adding a new memory
  - `graph_generation` GraphGeneration — Graph generation configuration
    - `mode` 'auto' | 'manual' — Graph generation modes
    - `auto` AutoGraphGeneration — AI-powered graph generation with optional guidance
      - `schema_id` string, nullable — Force AI to use this specific schema instead of auto-selecting
      - `simple_schema_mode` boolean — Limit AI to system + one user schema for consistency
      - `property_overrides` PropertyOverrideRule[], nullable — Override specific property values in AI-generated nodes with match conditions
        - `nodeLabel` string, required — Node type to apply overrides to (e.g., 'User', 'SecurityBehavior')
        - `match` object, nullable — Optional conditions that must be met for override to apply. If not provided, applies to all nodes of this type
        - `set` object, required — Properties to set/override on matching nodes
    - `manual` ManualGraphGeneration — Complete manual control over graph structure
      - `nodes` GraphOverrideNode[], required — Exact nodes to create
        - `id` string, required — **REQUIRED**: Unique identifier for this node. Must be unique within this request. Relationships reference this via source_node_id/target_node_id. Example: 'person_john_123', 'finding_cve_2024_1234'
        - `label` string, required — **REQUIRED**: Node type from your UserGraphSchema. View available types at GET /v1/schemas. System types: Memory, Person, Company, Project, Task, Insight, Meeting, Opportunity, Code
        - `properties` object, required — **REQUIRED**: Node properties matching your UserGraphSchema definition. Must include: (1) All required properties from your schema, (2) unique_identifiers if defined (e.g., 'email' for Person) to enable MERGE deduplication. View schema requirements at GET /v1/schemas
      - `relationships` GraphOverrideRelationship[] — Exact relationships to create
        - `source_node_id` string, required — **REQUIRED**: Must exactly match the 'id' field of a node defined in the 'nodes' array of this request
        - `target_node_id` string, required — **REQUIRED**: Must exactly match the 'id' field of a node defined in the 'nodes' array of this request
        - `relationship_type` string, required — **REQUIRED**: Relationship type from your UserGraphSchema. View available types at GET /v1/schemas. System types: WORKS_FOR, WORKS_ON, HAS_PARTICIPANT, DISCUSSES, MENTIONS, RELATES_TO, CREATED_BY
        - `properties` object, nullable — Optional relationship properties (e.g., {'since': '2024-01-01', 'role': 'manager'})
  - `content` string, required — The content of the memory item you want to add to memory
  - `type` 'text' | 'code_snippet' | 'document' — Valid memory types
  - `metadata` MemoryMetadata — Metadata for memory request
    - `hierarchical_structures` string, nullable — Hierarchical structures to enable navigation from broad topics to specific ones
    - `createdAt` string, nullable — ISO datetime when the memory was created
    - `location` string, nullable
    - `topics` string[], nullable
    - `emoji tags` string[], nullable
    - `emotion tags` string[], nullable
    - `conversationId` string, nullable
    - `sourceUrl` string, nullable
    - `role` 'user' | 'assistant' — Role of the message sender
    - `category` union — Memory category based on role. For users: preference, task, goal, fact, context. For assistants: skills, learning, task, goal, fact, context.
      - 'preference' | 'task' | 'goal' | 'fact' | 'context' — Memory categories for user messages
      - 'skills' | 'learning' | 'task' | 'goal' | 'fact' | 'context' — Memory categories for assistant messages
    - `user_id` string, nullable
    - `external_user_id` string, nullable
    - `external_user_read_access` string[], nullable
    - `external_user_write_access` string[], nullable
    - `user_read_access` string[], nullable
    - `user_write_access` string[], nullable
    - `workspace_read_access` string[], nullable
    - `workspace_write_access` string[], nullable
    - `role_read_access` string[], nullable
    - `role_write_access` string[], nullable
    - `namespace_read_access` string[], nullable
    - `namespace_write_access` string[], nullable
    - `organization_read_access` string[], nullable
    - `organization_write_access` string[], nullable
    - `pageId` string, nullable
    - `sourceType` string, nullable
    - `workspace_id` string, nullable
    - `upload_id` string, nullable — Upload ID for document processing workflows
    - `organization_id` string, nullable
    - `namespace_id` string, nullable
    - `sessionId` string, nullable
    - `post` string, nullable
    - `userMessage` string, nullable
    - `assistantMessage` string, nullable
    - `relatedGoals` string[], nullable
    - `relatedUseCases` string[], nullable
    - `relatedSteps` string[], nullable
    - `goalClassificationScores` number[], nullable
    - `useCaseClassificationScores` number[], nullable
    - `stepClassificationScores` number[], nullable
    - `customMetadata` object, nullable — Optional object for arbitrary custom metadata fields. Only string, number, boolean, or list of strings allowed. Nested dicts are not allowed.
  - `context` ContextItem[], nullable — Context can be conversation history or any relevant context for a memory item
    - `role` 'user' | 'assistant', required
    - `content` string, required
  - `relationships_json` RelationshipItem[], nullable — Array of relationships that we can use in Graph DB (neo4J)
    - `relation_type` string, required
    - `related_item_id` string, nullable
    - `relationship_type` 'previous_memory_item_id' | 'all_previous_memory_items' | 'link_to_id' — Enum for relationship types
    - `related_item_type` string, nullable — Legacy field - not used in processing
    - `metadata` object
  - `organization_id` string, nullable — Optional organization ID for multi-tenant memory scoping. When provided, memory is associated with this organization.
  - `namespace_id` string, nullable — Optional namespace ID for multi-tenant memory scoping. When provided, memory is associated with this namespace.

## Response `200`

Memory successfully added

- AddMemoryResponse — Unified response model for add_memory API endpoint (success or error).
  - `code` integer — HTTP status code
  - `status` string — 'success' or 'error'
  - `data` AddMemoryItem[], nullable — List of memory items if successful
    - `memoryId` string, required
    - `createdAt` string, date-time, required
    - `objectId` string, required
    - `memoryChunkIds` string[]
  - `error` string, nullable — Error message if failed
  - `details` unknown

## Other responses

- `207` — Memory added with degraded functionality
- `400` — Bad request
- `401` — Unauthorized
- `403` — Subscription limit reached
- `413` — Content too large
- `415` — Unsupported Media Type
- `422` — Validation Error
- `500` — Internal server error

## Changes

- **2025-11-19** `2422ab514a9d` — 4 info
  - added the new optional request property `metadata/anyOf[subschema #1: MemoryMetadata]/namespace_read_access`
  - added the new optional request property `metadata/anyOf[subschema #1: MemoryMetadata]/namespace_write_access`
  - added the new optional request property `metadata/anyOf[subschema #1: MemoryMetadata]/organization_read_access`
  - added the new optional request property `metadata/anyOf[subschema #1: MemoryMetadata]/organization_write_access`
- **2025-11-07** `14ff13755871` — 10 info
  - added the new optional request property `graph_generation`
  - added the new optional request property `metadata/anyOf[subschema #1: MemoryMetadata]/category`
  - added the new optional request property `metadata/anyOf[subschema #1: MemoryMetadata]/namespace_id`
  - added the new optional request property `metadata/anyOf[subschema #1: MemoryMetadata]/organization_id`
  - …6 more

[Change history](https://skmtc.dev/papr-ai/apis/papr-memory-api/changes/v1/memory/post.md)

---

[API](https://skmtc.dev/papr-ai/apis/papr-memory-api.md) · [All operations](https://skmtc.dev/papr-ai/apis/papr-memory-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/papr-ai/papr-memory-api/revisions/ea5bcad7e1ee/schema)