Memory API

Authorization: Bearer pmem_...

pip install parcle
export PARCLE_API_KEY="pmem_..."

from parcle import Parcle

# Reads PARCLE_API_KEY from the environment if api_key is omitted.
client = Parcle(api_key="pmem_...")

# 1. Create the user you'll be storing memory for.
#    Call this once per user before ingesting.
client.create_user(user_id="ada", name="Ada Lovelace", timezone="UTC")

# 2. Write a conversation into memory.
#    Omit session_id to start a new session; pass one to append.
dialog = client.ingest_dialog(
    user_id="ada",
    messages=[
        {"role": "user",      "content": "I'm allergic to peanuts."},
        {"role": "assistant", "content": "Got it -- I'll avoid peanuts in suggestions."},
    ],
    tag={"app": "diet-tracker"},
)

# Append more turns to the same session.
client.ingest_dialog(
    user_id="ada",
    session_id=dialog.session_id,
    messages=[
        {"role": "user", "content": "Also, I don't eat shellfish."},
    ],
)

# 3. Ingest a file (PDF, Markdown, text, DOCX, PPTX, XLSX, ...).
file_result = client.ingest_file(
    user_id="ada",
    file="diet-notes.pdf",
    tag={"app": "diet-tracker", "source": "file"},
)

# Ingestion waits until content is searchable by default.
# Pass wait=False to return immediately, then call
# client.wait_until_ready(user_id, event_id) yourself.

# 4. Ask a question -- get an answer with confidence and citations.
result = client.search(
    user_id="ada",
    query="What food should I avoid?",
    tag_filter={"app": "diet-tracker"},
)

print(result.answer)      # "You're allergic to peanuts and don't eat shellfish."
print(result.confidence)  # 0.92
print(result.citations)   # [Citation(type='session', id='ses_...')]

# 5. Delete memory when needed.
client.delete_by_session(user_id="ada", session_id=dialog.session_id)
client.delete_by_file(user_id="ada", file_id=file_result.file_id)

export PARCLE_API_KEY="pmem_..."
export PARCLE_BASE_URL="https://api.parcle.ai"

curl -X POST "$PARCLE_BASE_URL/v1/users" \
  -H "Authorization: Bearer $PARCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "ada",
    "name": "Ada Lovelace",
    "timezone": "UTC"
  }'

user = client.create_user(user_id="ada", name="Ada Lovelace", timezone="UTC")
print(user.user_id, user.is_new)  # "ada" True

{
  "user_id": "ada",
  "name": "Ada Lovelace",
  "timezone": "UTC",
  "is_new": true
}

curl -X POST "$PARCLE_BASE_URL/v1/memories/ingest_dialog" \
  -H "Authorization: Bearer $PARCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "ada",
    "messages": [
      {"role": "user", "content": "I'\''m allergic to peanuts."},
      {"role": "assistant", "content": "Got it -- I'\''ll avoid peanuts."}
    ],
    "tag": {"app": "diet-tracker"}
  }'

dialog = client.ingest_dialog(
    user_id="ada",
    messages=[
        {"role": "user", "content": "I'm allergic to peanuts."},
        {"role": "assistant", "content": "Got it -- I'll avoid peanuts."},
    ],
    tag={"app": "diet-tracker"},
)
print(dialog.session_id)  # "ses_abc123"

{"session_id": "ses_abc123", "event_id": "evt_xyz789"}

curl -X POST "$PARCLE_BASE_URL/v1/memories/ingest_dialog" \
  -H "Authorization: Bearer $PARCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "ada",
    "session_id": "ses_abc123",
    "messages": [
      {"role": "user", "content": "Also, I don'\''t eat shellfish."}
    ]
  }'

client.ingest_dialog(
    user_id="ada",
    session_id=dialog.session_id,
    messages=[{"role": "user", "content": "Also, I don't eat shellfish."}],
)

curl -X POST "$PARCLE_BASE_URL/v1/memories/ingest_files" \
  -H "Authorization: Bearer $PARCLE_API_KEY" \
  -F "user_id=ada" \
  -F "file=@diet-notes.pdf" \
  -F 'tag={"app":"diet-tracker","source":"file"}'

file_result = client.ingest_file(
    user_id="ada",
    file="diet-notes.pdf",
    tag={"app": "diet-tracker", "source": "file"},
)
print(file_result.file_id)  # "file_abc123"

{"file_id": "file_abc123", "event_id": "evt_xyz789"}

curl -X POST "$PARCLE_BASE_URL/v1/memories/events" \
  -H "Authorization: Bearer $PARCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "ada", "event_id": "evt_xyz789"}'

event = client.get_event(user_id="ada", event_id="evt_xyz789")
print(event.status)     # "ready"
print(event.is_ready)   # True

{"event_id": "evt_xyz789", "status": "ready", "error": null}

curl -N -X POST "$PARCLE_BASE_URL/v1/memories/search" \
  -H "Authorization: Bearer $PARCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "user_id": "ada",
    "query": "What food should I avoid?",
    "tag_filter": {"app": "diet-tracker"}
  }'

result = client.search(
    user_id="ada",
    query="What food should I avoid?",
    tag_filter={"app": "diet-tracker"},
)
print(result.answer)      # "You're allergic to peanuts and don't eat shellfish."
print(result.confidence)  # 0.92
print(result.citations)   # [Citation(type='session', id='ses_...')]

: keepalive

: keepalive

event: final
data: {"answer": "You're allergic to peanuts.", "confidence": 0.92, "citations": [{"type": "session", "id": "ses_abc123"}]}

curl -X POST "$PARCLE_BASE_URL/v1/memories/sources" \
  -H "Authorization: Bearer $PARCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "ada",
    "type": "session",
    "tag_filter": {"app": "diet-tracker"}
  }'

page = client.list_sources(user_id="ada", type="session")
for source in page.sources:
    print(source.id, source.type, source.tag)

# Or iterate across all pages automatically:
for source in client.iter_sources(user_id="ada"):
    print(source.id)

{
  "sources": [
    {
      "id": "ses_abc123",
      "type": "session",
      "updated_at": "2025-06-20T12:00:00Z",
      "tag": {"app": "diet-tracker"}
    }
  ],
  "page": 1,
  "total_pages": 1,
  "total": 1
}

curl -X POST "$PARCLE_BASE_URL/v1/memories/sessions" \
  -H "Authorization: Bearer $PARCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "ada", "session_id": "ses_abc123"}'

session = client.get_session(user_id="ada", session_id="ses_abc123")
for msg in session.messages:
    print(msg.role, msg.content)

{
  "session_id": "ses_abc123",
  "messages": [
    {"role": "user", "content": "I'm allergic to peanuts."},
    {"role": "assistant", "content": "Got it -- I'll avoid peanuts."}
  ],
  "tag": {"app": "diet-tracker"}
}

curl -X DELETE "$PARCLE_BASE_URL/v1/memories/by_session" \
  -H "Authorization: Bearer $PARCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "ada", "session_id": "ses_abc123"}'

client.delete_by_session(user_id="ada", session_id="ses_abc123")

curl -X DELETE "$PARCLE_BASE_URL/v1/memories/by_file" \
  -H "Authorization: Bearer $PARCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "ada", "file_id": "file_abc123"}'

client.delete_by_file(user_id="ada", file_id="file_abc123")

curl -X DELETE "$PARCLE_BASE_URL/v1/memories/by_tag" \
  -H "Authorization: Bearer $PARCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "ada", "tag_filter": {"app": "diet-tracker"}}'

client.delete_by_tag(user_id="ada", tag_filter={"app": "diet-tracker"})

{"deleted": true, "deleted_count": 1}

{
  "error": {
    "code": "invalid_request",
    "message": "A human-readable error message.",
    "request_id": "req_..."
  }
}