/memory

LiteLLM 프록시에서 사용자·팀 범위의 메모리 항목을 저장하고 조회하는 CRUD 엔드포인트예요. 대화 컨텍스트, 에이전트 메모리, 팀 플레이북, 또는 사용자·팀 범위의 키-값 데이터를 지속하는 데 사용하세요.

출처: 문서

본문

개요 (Overview)

기능	지원	참고
메모리 생성	✅	`POST /v1/memory`
메모리 목록	✅	선택적 필터링이 있는 `GET /v1/memory`
키로 메모리 가져오기	✅	`GET /v1/memory/{key}`
메모리 업서트	✅	`PUT /v1/memory/{key}`
메모리 삭제	✅	`DELETE /v1/memory/{key}`
사용자 범위 접근	✅	`user_id` 범위의 항목
팀 범위 접근	✅	`team_id` 범위의 항목
JSON 메타데이터	✅	항목당 임의 JSON 메타데이터
페이지네이션	✅	구성 가능한 페이지 크기의 페이지 기반
키 접두사 필터링	✅	Redis 스타일 네임스페이스 스캔
감사 추적	✅	타임스탬프가 있는 `created_by`, `updated_by`
지원 LiteLLM 버전	`v1.83.10+`

사전 요구사항 (Prerequisites)

PostgreSQL 데이터베이스가 연결된 LiteLLM Proxy 실행
데이터베이스 마이그레이션 적용(LiteLLM_MemoryTable이 자동 생성됨)
인증을 위한 유효한 API 키

추가 config.yaml 항목은 필요 없어요. 프록시가 연결된 데이터베이스와 함께 시작하면 엔드포인트가 자동으로 제공돼요.

빠른 시작 (Quick Start)

메모리 항목 생성 (Create a Memory Entry)

curl:

curl -X POST "http://localhost:4000/v1/memory" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "user:123:preferences",
    "value": "Prefers concise responses. Timezone: PST.",
    "metadata": {"tags": ["preferences", "user-settings"]}
  }'

Python (httpx):

import httpx

client = httpx.Client(
    base_url="http://localhost:4000",
    headers={"Authorization": "Bearer sk-<your-litellm-api-key>"},
)

response = client.post("/v1/memory", json={
    "key": "user:123:preferences",
    "value": "Prefers concise responses. Timezone: PST.",
    "metadata": {"tags": ["preferences", "user-settings"]},
})
print(response.json())

응답:

{
  "memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "key": "user:123:preferences",
  "value": "Prefers concise responses. Timezone: PST.",
  "metadata": {"tags": ["preferences", "user-settings"]},
  "user_id": "user-123",
  "team_id": "team-abc",
  "created_at": "2025-04-21T12:00:00Z",
  "created_by": "user-123",
  "updated_at": "2025-04-21T12:00:00Z",
  "updated_by": "user-123"
}

메모리 목록 (List Memories)

curl:

curl "http://localhost:4000/v1/memory" \
  -H "Authorization: Bearer ***"

키 접두사로 필터링:

curl "http://localhost:4000/v1/memory?key_prefix=user:123:" \
  -H "Authorization: Bearer ***"

결과 페이지네이션:

curl "http://localhost:4000/v1/memory?page=2&page_size=10" \
  -H "Authorization: Bearer ***"

Python (httpx):

# List all
response = client.get("/v1/memory")
print(response.json())

# Filter by key prefix
response = client.get("/v1/memory", params={"key_prefix": "user:123:"})
print(response.json())

# Paginate
response = client.get("/v1/memory", params={"page": 2, "page_size": 10})
print(response.json())

응답:

{
  "memories": [
    {
      "memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "key": "user:123:preferences",
      "value": "Prefers concise responses. Timezone: PST.",
      "metadata": {"tags": ["preferences", "user-settings"]},
      "user_id": "user-123",
      "team_id": "team-abc",
      "created_at": "2025-04-21T12:00:00Z",
      "created_by": "user-123",
      "updated_at": "2025-04-21T12:00:00Z",
      "updated_by": "user-123"
    }
  ],
  "total": 1
}

키로 메모리 가져오기 (Get a Memory by Key)

curl:

curl "http://localhost:4000/v1/memory/user:123:preferences" \
  -H "Authorization: Bearer ***"

Python (httpx):

response = client.get("/v1/memory/user:123:preferences")
print(response.json())

메모리 업데이트(Upsert) (Update (Upsert) a Memory)

키가 있으면 업데이트하고, 없으면 새 항목을 만들어요.

curl:

curl -X PUT "http://localhost:4000/v1/memory/user:123:preferences" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "Prefers concise responses. Timezone: EST. Language: English.",
    "metadata": {"tags": ["preferences", "user-settings"], "version": 2}
  }'

Python (httpx):

response = client.put("/v1/memory/user:123:preferences", json={
    "value": "Prefers concise responses. Timezone: EST. Language: English.",
    "metadata": {"tags": ["preferences", "user-settings"], "version": 2},
})
print(response.json())

메모리 삭제 (Delete a Memory)

curl:

curl -X DELETE "http://localhost:4000/v1/memory/user:123:preferences" \
  -H "Authorization: Bearer ***"

Python (httpx):

response = client.delete("/v1/memory/user:123:preferences")
print(response.json())

응답:

{
  "key": "user:123:preferences",
  "deleted": true
}

API 참조 (API Reference)

POST `/v1/memory`

새 메모리 항목을 생성해요.

요청 본문 (Request Body):

파라미터	타입	필수	설명
`key`	string	✅	전역 고유 키. 네임스페이스 키 사용(예: `user:123:notes`).
`value`	string	✅	메모리 내용. 보통 markdown 또는 일반 텍스트.
`metadata`	any (JSON)	❌	선택적 JSON 메타데이터(dict, list, scalar).
`user_id`	string	❌	사용자 범위. 기본값은 호출자의 `user_id`. 관리자 전용 오버라이드.
`team_id`	string	❌	팀 범위. 기본값은 호출자의 `team_id`. 관리자 전용 오버라이드.

응답: 201, 생성된 LiteLLM_MemoryRow 반환.

GET `/v1/memory`

호출자에게 보이는 메모리 항목을 목록화해요.

쿼리 파라미터 (Query Parameters):

파라미터	타입	기본값	설명
`key`	string	—	정확한 키 일치로 필터링.
`key_prefix`	string	—	키 접두사로 필터링(예: `user:123:`). `key`보다 우선.
`page`	int	1	페이지 번호(1부터 시작).
`page_size`	int	50	페이지당 항목 수(최대 500).

응답: 200, memories 배열과 total 개수를 가진 MemoryListResponse 반환.

GET `/v1/memory/{key}`

키로 단일 메모리 항목을 가져와요.

경로 파라미터 (Path Parameters):

파라미터	타입	설명
`key`	string	조회할 메모리 키.

응답: 200, LiteLLM_MemoryRow 반환.

PUT `/v1/memory/{key}`

메모리 항목을 업서트해요. 키가 없으면 항목을 생성하고, 있으면 업데이트해요.

경로 파라미터 (Path Parameters):

파라미터	타입	설명
`key`	string	생성하거나 업데이트할 메모리 키.

요청 본문 (Request Body):

파라미터	타입	필수	설명
`value`	string	✅ (생성 시)	메모리 내용. 생성 시 필수, 업데이트 시 선택.
`metadata`	any (JSON)	❌	업데이트된 메타데이터. 생략하면 기존 값 유지. `null`로 설정하면 초기화.
`user_id`	string	❌	생성 시에만 사용. 관리자 전용 오버라이드.
`team_id`	string	❌	생성 시에만 사용. 관리자 전용 오버라이드.

응답: 200, 생성/업데이트된 LiteLLM_MemoryRow 반환.

DELETE `/v1/memory/{key}`

키로 메모리 항목을 삭제해요.

경로 파라미터 (Path Parameters):

파라미터	타입	설명
`key`	string	삭제할 메모리 키.

응답: 200, {"key": "...", "deleted": true} 반환.

응답 객체 (Response Object)

메모리 항목을 반환하는 모든 엔드포인트는 이 스키마를 사용해요:

{
  "memory_id": "string (UUID)",
  "key": "string",
  "value": "string",
  "metadata": "any (JSON) or null",
  "user_id": "string or null",
  "team_id": "string or null",
  "created_at": "datetime",
  "created_by": "string",
  "updated_at": "datetime",
  "updated_by": "string"
}

접근 제어 (Access Control)

메모리 항목은 user_id와 team_id로 범위가 정해지며, 역할 기반 가시성과 쓰기 접근이 적용돼요.

가시성(읽기) (Visibility (Read))

역할	볼 수 있는 것
프록시 관리자(Proxy Admin)	모든 메모리 항목
일반 사용자(Regular User)	`user_id`가 자신과 일치하거나 `team_id`가 자신과 일치하는 항목

쓰기 접근(업데이트/삭제) (Write Access (Update / Delete))

시나리오	쓸 수 있는 사람
항목에 호출자와 일치하는 `user_id`가 있음	소유자가 업데이트/삭제 가능
팀 범위 전용 항목(`user_id` 없음)	팀 관리자와 조직 관리자만
모든 항목	프록시 관리자

info — 팀 멤버는 팀 범위 항목을 읽을 수 있지만 팀 관리자만 수정·삭제할 수 있어요. 이는 팀원들이 서로의 항목을 덮어쓰는 것을 방지해요.

생성 시 범위 지정 (Scoping on Create)

user_id와 team_id는 기본적으로 API 키에서 가져온 호출자 신원으로 정해져요
프록시 관리자는 user_id / team_id를 오버라이드해 다른 사용자나 팀의 항목을 만들 수 있어요
관리자가 아닌 호출자는 user_id 또는 team_id 중 하나 이상 없이는 항목을 만들 수 없어요

키 명명 규칙 (Key Naming Conventions)

키는 전역적으로 고유해요. 항목을 구성하려면 네임스페이스 키를 사용하세요:

user:{user_id}:preferences      # User preferences
user:{user_id}:context          # Conversation context
team:{team_id}:playbook         # Team playbook
agent:{agent_id}:memory         # Agent memory
project:{project_id}:config     # Project configuration

목록 엔드포인트에서 key_prefix를 사용해 네임스페이스의 모든 항목을 스캔할 수 있어요:

# Get all entries for a user
curl "http://localhost:4000/v1/memory?key_prefix=user:123:" \
  -H "Authorization: Bearer ***"

오류 코드 (Error Codes)

상태 코드	의미
`200`	성공 (GET, PUT, DELETE)
`201`	생성됨 (POST)
`400`	잘못된 입력(필수 필드 누락, 빈 PUT 본문, 고아 행)
`403`	권한 거부(쓰기 접근 위반, 관리자가 아닌 범위 오버라이드)
`404`	키를 찾을 수 없거나 호출자에게 보이지 않음
`409`	생성 시 중복 키
`500`	내부 서버 오류(데이터베이스 문제)

더 알아보기 (Learn more)

메모리 엔드포인트 — 메모리 CRUD API

/memory

/memory

본문

개요 (Overview)

사전 요구사항 (Prerequisites)

빠른 시작 (Quick Start)

메모리 항목 생성 (Create a Memory Entry)

메모리 목록 (List Memories)

키로 메모리 가져오기 (Get a Memory by Key)

메모리 업데이트(Upsert) (Update (Upsert) a Memory)

메모리 삭제 (Delete a Memory)

API 참조 (API Reference)

POST /v1/memory

GET /v1/memory

GET /v1/memory/{key}

PUT /v1/memory/{key}

DELETE /v1/memory/{key}

응답 객체 (Response Object)

접근 제어 (Access Control)

가시성(읽기) (Visibility (Read))

쓰기 접근(업데이트/삭제) (Write Access (Update / Delete))

생성 시 범위 지정 (Scoping on Create)

키 명명 규칙 (Key Naming Conventions)

오류 코드 (Error Codes)

더 알아보기 (Learn more)

POST `/v1/memory`

GET `/v1/memory`

GET `/v1/memory/{key}`

PUT `/v1/memory/{key}`

DELETE `/v1/memory/{key}`