# How TeamAI Migrates from the Legacy .teamai/ Directory to the New Partitioned Layout

> TeamAI automatically migrates your legacy .teamai/ data to a new partitioned layout upon upgrade. Experience isolated storage for machine-local artifacts with this seamless transition.

- Repository: [Tencent/teamai-cli](https://github.com/tencent/teamai-cli)
- Tags: migration-guide
- Published: 2026-09-11

---

**TeamAI automatically migrates legacy data from the repository-root `.teamai/` folder to a partitioned directory at `~/.teamai/projects/<project-slug>/` the first time you run a CLI command after upgrading, ensuring isolated storage for machine-local artefacts.**

The Tencent/teamai-cli project originally stored all local data—knowledge bases, MCP manifests, and caches—inside a hidden `.teamai/` directory at the root of each workspace. This caused data collisions when multiple developers shared a repository and polluted the source tree with tool-generated files. To solve this, the codebase now implements a **partitioned data home** that lives outside the project tree, with an idempotent migration routine that preserves existing data while eliminating the legacy layout.

## Why the Legacy .teamai/ Layout Was Problematic

The original design placed all TeamAI artefacts directly inside the workspace:

- **Data Collisions**: When multiple developers cloned the same repository, their local learning files and MCP configurations overwrote each other because they all wrote to the same relative path.
- **Workspace Pollution**: Version control tools and backup scripts had to explicitly ignore the hidden folder, and the mixture of source and generated files complicated repository maintenance.

According to the Tencent/teamai-cli source code, the new partitioned layout stores data under the user's home directory, scoped by a deterministic project slug derived from the Git remote URL.

## The Migration Pipeline: Step-by-Step

The migration logic is defined in [`src/migrate.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/migrate.ts) and executes transparently on the first CLI invocation after detecting a legacy installation.

### Step 1: Detecting the Legacy Layout

The CLI first checks for the existence of the old data home by resolving `path.join(workspaceRoot, '.teamai')`. If this directory exists, the migration sequence begins.

```typescript
// src/migrate.ts
const legacyTeamaiHome = path.join(workspaceRoot, '.teamai');
if (existsSync(legacyTeamaiHome)) {
  await migrateLegacyTeamai(workspaceRoot);
}

```

### Step 2: Resolving the Partition Anchor

Before moving data, the system calculates the new destination. In [`src/utils/partition.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/utils/partition.ts), the CLI parses the project's Git remote URL to generate a reproducible `projectSlug` (e.g., `github.com_Tencent_teamai-cli`). The new data home becomes:

```typescript
// src/utils/partition.ts
const newHome = path.join(os.homedir(), '.teamai', 'projects', projectSlug);

```

This deterministic naming ensures that every clone of the same repository maps to the same partition, enabling consistent knowledge sharing across different local copies.

### Step 3: Migrating MCP Configuration

If the legacy folder contains a [`managed-mcp.json`](https://github.com/Tencent/teamai-cli/blob/main/managed-mcp.json) file, the `migrateManagedMcp()` helper copies it to the partitioned location. This preserves your MCP server definitions without requiring manual reconfiguration.

```typescript
// src/migrate.ts
await migrateManagedMcp(
  path.join(legacyTeamaiHome, 'managed-mcp.json'),
  path.join(newHome, 'managed-mcp.json')
);

```

### Step 4: Moving Knowledge Artefacts

All learning data, indexes, and caches are relocated using `moveDirContents()`, which recursively walks the source directory and moves entries from `legacyTeamaiHome/knowledge` to `newHome/knowledge`. This operation is atomic and reversible until the final cleanup stage.

```typescript
// src/migrate.ts
await moveDirContents(
  path.join(legacyTeamaiHome, 'knowledge'),
  path.join(newHome, 'knowledge')
);

```

### Step 5: Updating Internal References

After successful data movement, the CLI updates its runtime configuration in [`src/config.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/config.ts). Subsequent commands query `getDataHome()` from [`src/utils/home.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/utils/home.ts), which now returns the partitioned path rather than the legacy workspace-relative location.

```typescript
// src/utils/home.ts
export function getDataHome(): string {
  return path.join(os.homedir(), '.teamai', 'projects', getProjectSlug());
}

```

### Step 6: Cleaning Up Legacy Data

Once the migration succeeds and the new configuration is verified, the old `.teamai/` folder is removed from the workspace root. This cleanup is guarded by safety checks ensuring no other process holds file locks on the legacy directory.

## Implementation Details and Code Examples

You can verify the migration status programmatically or invoke the migration manually in edge cases.

**Checking migration status:**

```typescript
import { existsSync } from 'fs';
import { getDataHome } from './utils/home';

const hasMigrated = existsSync(getDataHome());
console.log(hasMigrated ? 'Using partitioned layout' : 'Legacy layout detected');

```

**Manually triggering migration:**

```typescript
import { migrateLegacyTeamai } from './migrate';

// Force migration check for a specific workspace
await migrateLegacyTeamai('/path/to/project');

```

**Accessing the partitioned data home:**

```typescript
import { getDataHome } from './utils/home';
import path from 'path';

const projectHome = getDataHome(); // ~/.teamai/projects/<slug>
const knowledgeDir = path.join(projectHome, 'knowledge');

```

## Summary

- **Automatic Detection**: The CLI checks for `<workspaceRoot>/.teamai/` in [`src/migrate.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/migrate.ts) and triggers migration only when legacy data exists.
- **Deterministic Partitioning**: The new home uses a slug derived from the Git remote URL, ensuring consistency across clones.
- **Data Integrity**: The `moveDirContents()` utility preserves all knowledge files and MCP configurations during the transfer.
- **Isolation**: All machine-local artefacts now live under `~/.teamai/projects/`, completely outside the source repository.
- **Idempotent Operation**: Running the migration multiple times is safe; the system skips already-migrated projects.

## Frequently Asked Questions

### Does the migration happen automatically?

Yes. According to the Tencent/teamai-cli source code, the first CLI command you run after upgrading detects the legacy `.teamai/` directory and executes the full migration sequence without requiring manual intervention. You do not need to run a separate migration command.

### What happens to my existing knowledge base?

All existing data is preserved. The `moveDirContents()` function in [`src/migrate.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/migrate.ts) recursively transfers every file from the legacy `knowledge/` subdirectory to the new partitioned location. Your learning history, indexes, and caches remain intact and accessible after migration.

### How is the partition directory name determined?

The directory name is a slug generated from the repository's Git remote URL. The logic in [`src/utils/partition.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/utils/partition.ts) converts URLs like `https://github.com/Tencent/teamai-cli.git` into identifiers like `github.com_Tencent_teamai-cli`, ensuring that every clone of the same repository maps to the same data partition.

### Can I revert to the legacy .teamai/ layout?

No, the migration is designed as a one-way transition. After successful migration, [`src/migrate.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/migrate.ts) removes the legacy `.teamai/` folder from your workspace, and the CLI exclusively uses `getDataHome()` from [`src/utils/home.ts`](https://github.com/Tencent/teamai-cli/blob/main/src/utils/home.ts) to resolve the partitioned path. Reverting would require manually moving data back and modifying the source code.