Metadata-Version: 2.4
Name: june-adk
Version: 0.1.0
Summary: Give your Google ADK agent a June memory — a local-first MemoryService backed by a searchable, cited June knowledge canvas, plus a backfill CLI for existing session databases.
Author-email: Junemind <access@januraine.ai>
License-Expression: MIT
Project-URL: Homepage, https://june.januraine.ai
Project-URL: Source, https://github.com/Junemind/june-adk
Project-URL: Releases, https://github.com/Junemind/June_releases
Keywords: google-adk,adk,agent-memory,memory-service,knowledge-graph,june
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-adk>=2
Provides-Extra: db
Requires-Dist: google-adk[db]>=2; extra == "db"
Requires-Dist: aiosqlite>=0.20; extra == "db"
Requires-Dist: greenlet>=3; extra == "db"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: google-adk[db]>=2; extra == "dev"
Requires-Dist: aiosqlite>=0.20; extra == "dev"
Requires-Dist: greenlet>=3; extra == "dev"
Dynamic: license-file

# june-adk

**Give your Google ADK agent a June memory.** ADK already defines a pluggable
memory seam — `BaseMemoryService` — but its production implementation sends
your agent's conversations to Vertex AI RAG in Google's cloud.
`june-adk` implements the same seam against [Junê](https://june.januraine.ai)
instead: your agent's history becomes a **local-first, searchable, cited
knowledge graph**, canvas-fenced like everything else in June.

```
your ADK agent ──▶ JuneMemoryService ──▶ June canvas (graph · search · citations)
                   (ADK's own seam)       local by default — your machine, your data
```

## The live seam — one object in your Runner

```bash
pip install june-adk
```

```python
from google.adk.runners import Runner
from june_adk import JuneMemoryService

memory = JuneMemoryService(
    june_url="http://127.0.0.1:8799",    # the Junê desktop app's local engine
    api_key="local",
    canvas="agent-memory",
    state_file=".june_adk_pushed.json",  # dedupe ledger, survives restarts
)
runner = Runner(agent=agent, app_name="my-app",
                session_service=session_service, memory_service=memory)
```

That's the whole integration. ADK's own memory tools (`load_memory`,
preload-memory) now read June, and `add_session_to_memory` /
`add_events_to_memory` write it. `JuneMemoryService.from_env()` builds from
the same `JUNE_BASE_URL` / `JUNE_API_KEY` / `JUNE_CANVAS` env vars that
june-mcp and june-langgraph use.

Contract fidelity, verified against the installed `google-adk` (not docs):

- `add_session_to_memory` — ADK says a session "may be added multiple times
  during its lifetime"; we honor that with **per-event delta dedup**, so
  repeated adds never duplicate and only new events ship.
- `add_events_to_memory` — the incremental path, treated as a delta exactly
  as the base class demands.
- `search_memory` → `SearchMemoryResponse` of `MemoryEntry` items, with
  June provenance (score, node id) in `custom_metadata`.
- **Fail-soft by default**: a memory write must never crash the agent — June
  being down logs one line and retries on the next add. Pass `strict=True`
  to raise instead. All HTTP runs in a worker thread; the event loop is
  never blocked.

## The backfill — history your app already saved

If your app persists sessions with ADK's `DatabaseSessionService`, the
history that *already exists* can be brought into June without touching your
code:

```bash
pip install "june-adk[db]"
june-adk sync --db sessions.db          # one incremental catch-up pass
june-adk watch --db sessions.db         # keep syncing (Ctrl+C to stop)
june-adk doctor --db sessions.db        # PASS/FAIL every part of the setup
```

Discovery is metadata-only SQL (which app/user scopes exist); **content is
always read through ADK's own `DatabaseSessionService`**, so ADK deserializes
its events — never us. Bare file paths and `sqlite://` URLs are quietly
upgraded to the async driver ADK 2.x requires. Server databases (Postgres,
MySQL) work too — pass `--app` and `--user`. Every pass is incremental via
the same ledger the live seam uses; re-running never duplicates.

## 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](https://pypi.org/project/june-mcp) at the
same canvas so Claude (or any MCP agent) can answer over your ADK agent's
entire history. One memory, every agent.

Part of a family: [june-langgraph](https://pypi.org/project/june-langgraph)
does the same for LangGraph checkpointers.

## License

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