june-openai-agents

Give your OpenAI Agents SDK agent a June memory. The SDK's Sessions are built for resuming a conversation — long-term, searchable memory is left as an exercise. This package closes the loop on both sides against Junê: conversations flow into a local-first, searchable, cited knowledge graph as your agent runs, and the agent can search that memory back while answering.

Runner ──▶ JuneSession (wraps your Session) ──▶ June canvas ◀── june_memory_tool
             writes as the agent runs             graph · cited     the agent reads back

Write side — wrap the session you already use

pip install june-openai-agents

from agents import Agent, Runner, SQLiteSession
from june_openai_agents import JuneSession

session = JuneSession(
    SQLiteSession("thread-42", "conversations.db"),   # any Session works
    june_url="http://127.0.0.1:8799",     # the Junê desktop app's local engine
    api_key="local",
    canvas="agent-memory",
    state_file=".june_oai_pending.json",  # retry buffer, survives restarts
)
result = await Runner.run(agent, "hello", session=session)

JuneSession satisfies the SDK's runtime-checkable Session protocol — attributes included — so the Runner can't tell the difference. Every operation delegates to your real session first; each batch of new items then mirrors to June while they're still live dicts. Fail-soft: June being down never breaks a run — unmirrored items go to a persisted pending buffer and flush on the next add (strict=True raises instead). Tool-call frames, reasoning items and empty turns are filtered out — only conversation becomes memory. JuneSession.from_env(inner) reads the same JUNE_BASE_URL / JUNE_API_KEY / JUNE_CANVAS env vars as june-mcp.

Read side — one tool and the agent can recall

from agents import Agent
from june_openai_agents import june_memory_tool

agent = Agent(
    name="assistant",
    instructions="Use june_memory_search before answering questions about "
                 "prior conversations or saved knowledge.",
    tools=[june_memory_tool()],           # env-var config by default
)

The tool searches the same canvas the session writes into and returns matched knowledge as plain lines the model can ground on.

Backfill — history your app already saved

june-openai-agents sync --db conversations.db     # one incremental pass
june-openai-agents watch --db conversations.db    # keep syncing (Ctrl+C stops)
june-openai-agents doctor --db conversations.db   # PASS/FAIL the setup

Discovery is metadata-only SQL (which session ids exist); content is always read through the SDK's own SQLiteSession, so the SDK decodes its stored items — never us. Every pass is incremental via a per-item ledger; re-running never duplicates, and even a forced re-push is folded by June's read-side dedup.

What you get on the June side

The canvas behaves like any other: search it, ask cited questions over it in the Junê app, and point june-mcp at the same canvas so Claude can answer over your agent's entire history.

Part of a family: june-langgraph (LangGraph checkpointers) and june-adk (Google ADK's MemoryService) do the same for their frameworks.

License

MIT. The Junê engine itself is a separate, closed-source product — this connector is the open part, by design.