# Migrating to the `sdk/v0.4.0` + `memory/v0.1.0` split

> Status: `sdk/v0.4.0`, `memory/v0.1.0`, `sdkx/v0.4.0`, and
> `vessel/v0.3.0` are published.

This release makes the memory domain a first-class Go module. The important
change is the release boundary, not a broad source-breaking API cleanup like
`sdk/v0.3.0`.

## Release order

The modules were tagged in dependency order:

1. `sdk/v0.4.0`
2. `memory/v0.1.0`
3. `sdkx/v0.4.0`
4. `vessel/v0.3.0`

The resulting dependency graph is:

```text
sdk/v0.4.0
└── memory/v0.1.0
    ├── sdkx/v0.4.0
    └── vessel/v0.3.0
```

`sdkx` depends on `memory` because its deprecated retrieval wrappers forward to
`memory/retrieval/...`. `vessel` depends on `memory` for assembly helpers and
memory-backed runtime integrations.

## New module boundary

Use `github.com/GizClaw/flowcraft/memory` for memory-domain packages:

| Domain | Module/package family |
| --- | --- |
| Long-term recall | `memory/recall` |
| Conversation transcripts | `memory/history` |
| Knowledge retrieval | `memory/knowledge` |
| Retrieval indexes and scoring | `memory/retrieval` |
| Text/tokenization utilities | `memory/text` |

`sdk` remains the foundation for agent execution, graph runtime, LLM contracts,
tools, events, telemetry, and workspace primitives.

## Upgrade paths

### SDK-only users

If you only use agent / engine / graph / LLM / tool primitives:

```bash
go get github.com/GizClaw/flowcraft/sdk@v0.4.0
go mod tidy
```

### Memory users

If you use recall, history, knowledge, retrieval, or text helpers:

```bash
go get github.com/GizClaw/flowcraft/sdk@v0.4.0
go get github.com/GizClaw/flowcraft/memory@v0.1.0
go mod tidy
```

New code should import memory-domain packages from the `memory` module.

### SDKX users

If you use provider adapters or compatibility wrappers:

```bash
go get github.com/GizClaw/flowcraft/sdkx@v0.4.0
go mod tidy
```

`sdkx/v0.4.0` pins `sdk v0.4.0` and explicitly depends on `memory v0.1.0`.

### Vessel users

If you use the in-process runtime:

```bash
go get github.com/GizClaw/flowcraft/vessel@v0.3.0
go mod tidy
```

`vessel/v0.3.0` pins `sdk v0.4.0` and `memory v0.1.0`, and publishes the
`vessel/assembly` helpers.

## Compatibility notes

- This is mainly a module-boundary and dependency-pin release.
- The v0.3 migration remains the source of truth for the large SDK API cleanup:
  see [`sdk/v0.3.0`](v0.3.0.md).
- Compatibility wrappers may still exist in older SDK/SDKX package families;
  prefer the `memory/...` import paths for new work.
- The example programs have not all been rewritten to the new import paths yet.
  Their README files intentionally continue to describe the code that is
  currently checked in.
