agent-openai-memory

Add memory capabilities to your agent. Use when: (1) User asks about 'memory', 'state', 'remember', 'conversation history', (2) Want to persist conversations or user preferences, (3) Adding checkpointing or long-term storage.

Quality

74%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/agent-openai-memory/SKILL.md

Stateful Memory with OpenAI Agents SDK Sessions

Name: agent-openai-memory
Rating: 63.2 (1 reviews)
Author: databricks

This template uses OpenAI Agents SDK Sessions with AsyncDatabricksSession to persist conversation history to a Databricks Lakebase instance.

How Sessions Work

Sessions automatically manage conversation history for multi-turn interactions:

Before each run: The session retrieves prior conversation history and prepends it to input
During the run: New items (user messages, responses, tool calls) are generated
After each run: All new items are automatically stored in the session

This eliminates the need to manually manage conversation state between runs.

Key Concepts

Concept	Description
Session	Stores conversation history for a specific `session_id`
`session_id`	Unique identifier linking requests to the same conversation
`AsyncDatabricksSession`	Session implementation backed by Databricks Lakebase
`LAKEBASE_AUTOSCALING_ENDPOINT`	Environment variable specifying the autoscaling Lakebase endpoint

How This Template Uses Sessions

Session Creation (`agent_server/agent.py`)

from databricks_openai.agents import AsyncDatabricksSession

session = AsyncDatabricksSession(
    session_id=get_session_id(request),
    autoscaling_endpoint=lakebase_config.autoscaling_endpoint,
    project=lakebase_config.autoscaling_project,
    branch=lakebase_config.autoscaling_branch,
)

result = await Runner.run(agent, messages, session=session)

Session ID Extraction (`agent_server/agent.py`)

The session_id is extracted from custom_inputs or auto-generated:

def get_session_id(request: ResponsesAgentRequest) -> str:
    if hasattr(request, "custom_inputs") and request.custom_inputs:
        if "session_id" in request.custom_inputs:
            return request.custom_inputs["session_id"]
    return str(uuid7())

Lakebase Config (`agent_server/utils.py`)

The autoscaling Lakebase config is read from env vars into a LakebaseConfig by init_lakebase_config() (priority: endpoint > project+branch):

lakebase_config = init_lakebase_config()  # reads LAKEBASE_AUTOSCALING_ENDPOINT / PROJECT / BRANCH

Prerequisites

Dependency: databricks-openai[memory] must be in pyproject.toml (already included)
Lakebase instance: You need an autoscaling Databricks Lakebase instance. See the lakebase-setup skill for creating and configuring one.
Environment variable: Set LAKEBASE_AUTOSCALING_ENDPOINT in your .env file:
```
LAKEBASE_AUTOSCALING_ENDPOINT=<your-endpoint>
```

Configuration Files

databricks.yml (Lakebase Resource)

Add the autoscaling postgres resource to your app:

resources:
  apps:
    agent_openai_advanced:
      name: "your-app-name"
      source_code_path: ./

      resources:
        # ... other resources (experiment, etc.) ...

        # Autoscaling Lakebase instance for session storage
        - name: 'postgres'
          postgres:
            branch: "projects/<project-name>/branches/<branch-name>"
            database: "projects/<project-name>/branches/<branch-name>/databases/<database-id>"
            permission: 'CAN_CONNECT_AND_CREATE'

databricks.yml config block (Environment Variables)

The LAKEBASE_AUTOSCALING_ENDPOINT env var is resolved from the postgres resource at deploy time. Add to your app's config.env in databricks.yml:

config:
        env:
          - name: LAKEBASE_AUTOSCALING_ENDPOINT
            value_from: "postgres"

.env (Local Development)

LAKEBASE_AUTOSCALING_ENDPOINT=<your-endpoint>

Testing Sessions

Test Multi-Turn Conversation Locally

# Start the server
uv run start-app

# First message - starts a new session
curl -X POST http://localhost:8000/invocations \
  -H "Content-Type: application/json" \
  -d '{"input": [{"role": "user", "content": "Hello, I live in SF!"}]}'

# Note the session_id from custom_outputs in the response

# Second message - continues the same session
curl -X POST http://localhost:8000/invocations \
  -H "Content-Type: application/json" \
  -d '{
      "input": [{"role": "user", "content": "What city did I say I live in?"}],
      "custom_inputs": {"session_id": "<session_id from previous response>"}
  }'

Test Streaming

curl -X POST http://localhost:8000/invocations \
  -H "Content-Type: application/json" \
  -d '{
      "input": [{"role": "user", "content": "Hello!"}],
      "stream": true
  }'

Troubleshooting

Issue	Cause	Solution
"Lakebase configuration is required"	Missing env var	Set `LAKEBASE_AUTOSCALING_ENDPOINT` in `.env`
SSL connection closed unexpectedly	Network/instance issue	Verify the Lakebase endpoint is reachable via the postgres API
Agent doesn't remember previous messages	Different session_id	Pass the same `session_id` via `custom_inputs` across requests
Permission denied	Missing Lakebase access	Add `postgres` resource to `databricks.yml` with `CAN_CONNECT_AND_CREATE`

Next Steps

Configure Lakebase: see lakebase-setup skill
Test locally: see run-locally skill
Deploy: see deploy skill

Repository: databricks/app-templates
Path: .claude/skills/agent-openai-memory/SKILL.md
Commit: fdc1b49

Last updated: 1 day ago
First committed: 4 months ago

Also appears in

databricks/app-templates

In sync

since May 6, 2026

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.