> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating to v3

> What was removed in Agentium v3, why, and the one-line replacement for each thing.

# Migrating to v3

v3 is a deletion release. Nothing new was added; a lot was taken away. Two changes
affect real code — toolkit imports and the `learning` flag — and the rest only affects
you if you were calling modules that never did much in the first place.

The main `@agentium/core` bundle went from **593.8 KB to 363.8 KB** (ESM, unminified), a
39% cut, because toolkits moved behind their own entry point and dead modules are gone.

## 1. Toolkit imports moved

This is the change most projects will hit. Concrete toolkits now come from
`@agentium/core/toolkits`:

```diff theme={null}
- import { Agent, openai, GitHubToolkit } from "@agentium/core";
+ import { Agent, openai } from "@agentium/core";
+ import { GitHubToolkit } from "@agentium/core/toolkits";
```

Import a single toolkit to keep the graph smaller still:

```typescript theme={null}
import { GitHubToolkit } from "@agentium/core/toolkits/github";
```

`toolkitCatalog` and `ToolkitCatalog` moved with them. The base abstractions did not —
`Toolkit`, `collectToolkitTools`, and `describeToolLibrary` are still at the root,
because writing your own toolkit shouldn't pull in all 30 first-party ones.

Every symbol that moved is a toolkit class, its config type, or the catalog. If
TypeScript tells you `'@agentium/core' has no exported member 'XToolkit'`, add
`/toolkits` to the import path.

## 2. `learning: true` is gone

`learning` always needed a vector store to do anything useful. Passing `true` quietly
gave you an in-memory store that vanished on restart, which looked like a working
feature and wasn't. It now takes a config object only:

```diff theme={null}
- learning: true
+ learning: { vectorStore: new InMemoryVectorStore() }
```

`Agent.deep()` no longer turns learning on for you, for the same reason. Turn it on
explicitly when you have somewhere real to put the vectors.

## 3. Removed modules

Each of these is gone from `@agentium/core`. The replacement column is what people were
actually reaching for.

| Removed                                                                   | Use instead                                                                                                  |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `Memory`                                                                  | `memory: { storage, summaries: true }`                                                                       |
| `UserMemory`                                                              | `memory: { userFacts: true, userProfile: true }`                                                             |
| `FlashMemoryStore`                                                        | `memory: { storage }` — sessions already persist                                                             |
| `CultureManager`                                                          | `contextFiles` (AGENTS.md) + `fileMemory` + `memory.learnings`                                               |
| `ContextCurator`                                                          | `contextCompactor` and `compressToolResults`                                                                 |
| `LearnedSkillStore`                                                       | `memory.learnings`                                                                                           |
| `SemanticToolSelector`                                                    | `toolResolver` (per-run tool lists) or `toolRouter`                                                          |
| `AgentScheduler`                                                          | `AgentQueue.schedule()` from `@agentium/queue`                                                               |
| `VersionStore`, `ABRouter`, `ShadowRunner`                                | Run two agents and compare; route in your own code                                                           |
| `AuditLogger`, `ComplianceReporter`, `ErasureManager`, `RetentionManager` | Subscribe to the [EventBus](/agents/events) for the trail; `memory.curator.clearAll({ userId })` for erasure |
| `planCapacity`, `SessionProfiler`, and the rest of `capacity/*`           | Measure with [metrics](/observability/overview) instead of estimating                                        |

The scheduling, versioning, and compliance modules stored data and emitted events, but
nothing in the agent loop ever read them back. They were reporting surfaces pretending
to be features, so they were cut rather than half-wired.

## 4. Removed `AgentConfig` fields

These fields were accepted and then ignored, or wired to a module that no longer exists:

| Removed field       | Notes                                                                                   |
| ------------------- | --------------------------------------------------------------------------------------- |
| `generateFollowups` | Also removes `result.followupSuggestions`                                               |
| `culture`           | See `contextFiles` + `fileMemory`                                                       |
| `contextCurator`    | See `contextCompactor`                                                                  |
| `versioning`        | No replacement                                                                          |
| `compliance`        | No replacement                                                                          |
| `tenant`            | Use `AgentFactory` + `TenantScopedStorage`; pass `tenantId` to `run()`                  |
| `rateLimit`         | `TokenRateLimiter` and `ConcurrencyLimiter` still exist — call them at your entry point |

Multi-tenancy itself did not go anywhere. `AgentFactory`, `ScopedStorage`, and
`TenantScopedStorage` are unchanged; only the config shortcut is gone. See
[Multi-tenant](/features/multi-tenant).

## 5. Never-emitted events

`AgentEventMap` had 41 keys that nothing ever emitted — capacity, compliance, versioning,
and scheduling events among them. Subscribing to one gave you a handler that never fired.
They're removed, leaving 37 real events, so a typo in an event name is now a type error
rather than silence. Everything you actually listen to is unchanged: `run.start`,
`run.complete`, `run.error`, `run.cancelled`, `run.stream.chunk`, `tool.call`,
`tool.result`, the `memory.*` and `voice.*` families, `context.compacted`, and
`reflection.critique`.

## 6. Storage stayed in core

Storage drivers were considered for extraction into `@agentium/storage` and deliberately
left in place. `InMemoryStorage`, `SqliteStorage`, `PostgresStorage`, `MongoDBStorage`,
`RedisStorage`, `MySQLStorage`, and `DynamoDBStorage` are still imported from
`@agentium/core`. Their database clients are optional peer dependencies, so a driver you
don't import costs you nothing.

## Checklist

1. Add `/toolkits` to toolkit imports — or run a find-and-replace on
   `Toolkit } from "@agentium/core"`.
2. Replace `learning: true` with `learning: { vectorStore }`, or drop it.
3. Delete `generateFollowups`, `culture`, `contextCurator`, `versioning`, `compliance`,
   `tenant`, and `rateLimit` from agent configs.
4. Typecheck. Everything in this guide surfaces as a compile error, not a runtime
   surprise.