# How to Initialize a New ai-memory Data Directory: Complete Setup Guide

> Initialize a new ai-memory data directory effortlessly. Run ai-memory init to set up Git version control, generate a cryptographic pepper, and create a default config file.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-08-28

---

**Run `ai-memory init` to create a new data directory with Git version control, cryptographic pepper generation, and a default configuration file.**

The `ai-memory` project stores all sessions, wiki pages, and indexed embeddings in a single **data directory** that must be initialized before first use. This guide walks through the initialization process, customization options, and the underlying source implementation in the [akitaonrails/ai-memory](https://github.com/akitaonrails/ai-memory) repository.

---

## What the init Command Does

Running `ai-memory init` performs six idempotent steps to prepare your environment:

1. **Selects the data directory** — Uses XDG data directories by default (`~/.local/share/ai-memory` on Linux, `~/Library/Application Support/ai-memory` on macOS, `%LOCALAPPDATA%\ai-memory` on Windows), or a custom path via `--data-dir`
2. **Creates directory structure** — Builds `data/`, `data/wiki/`, and `data/db/` subdirectories
3. **Initializes Git** — Runs `git init` for atomic wiki operations with history tracking
4. **Generates `token_pepper`** — Creates a random cryptographic value for token derivation, printed to stdout
5. **Writes [`config.toml`](https://github.com/akitaonrails/ai-memory/blob/main/config.toml)** — Places a minimal configuration file alongside the data directory
6. **Logs the location** — Outputs the final path for confirmation

All steps are **idempotent** — rerunning `ai-memory init` safely reaffirms the existing setup without overwriting data.

---

## Basic Initialization Commands

### Default Data Directory

```bash
ai-memory init

```

This uses the platform-specific XDG location and is the recommended approach for most users.

### Custom Data Directory

```bash
ai-memory --data-dir "$HOME/my-ai-data" init

```

The `--data-dir` flag overrides the default before executing the `init` sub-command.

### Verify the Setup

```bash

# Check the wiki directory exists

ls "$HOME/.local/share/ai-memory/wiki"

# Confirm Git repository is initialized

git -C "$HOME/.local/share/ai-memory/wiki" status

```

---

## Source Code Implementation

The initialization logic spans four core components in the Rust codebase:

### CLI Entry Point

In [[`crates/ai-memory-cli/src/main.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/main.rs)](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/main.rs), the CLI parses the `init` sub-command and delegates to the core initializer.

### Wiki Directory and Git Setup

The [[`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs)](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs) file contains `Wiki::new`, which:
- Creates the data directory structure
- Invokes `GitAdapter::open_or_init` to initialize the repository

The Git adapter in [[`crates/ai-memory-wiki/src/git.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/git.rs)](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/git.rs) handles the actual `git init` call with proper idempotency checks.

### Configuration and Pepper Generation

In [[`crates/ai-memory-cli/src/config.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/config.rs)](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/config.rs), the configuration logic:
- Generates a random `token_pepper` if missing
- Writes [`config.toml`](https://github.com/akitaonrails/ai-memory/blob/main/config.toml) with the data directory path and pepper value

The pepper is **never written to the Git repository** — it exists only in the local configuration file and is printed once during initialization for record-keeping.

---

## Design Benefits

The `init` command is deliberately **stand-alone**:
- No environment variables required
- No authentication tokens needed
- No network access involved

This makes it safe for packaging scripts, CI pipelines, and fresh host provisioning. The Git-backed wiki enables atomic writes (tmp + rename + fsync) with full version history.

---

## Summary

- **Use `ai-memory init`** to create a new data directory with all required structure
- **Default location** follows XDG standards; override with `--data-dir <PATH>`
- **Idempotent operation** — safe to run multiple times
- **Git version control** is initialized automatically for the wiki
- **Cryptographic pepper** is generated once and stored in [`config.toml`](https://github.com/akitaonrails/ai-memory/blob/main/config.toml)

---

## Frequently Asked Questions

### What happens if I run `ai-memory init` on an existing directory?

The command is fully idempotent. It will detect the existing configuration and data structure, then simply confirm the current setup without overwriting files or regenerating the pepper.

### Where is the `token_pepper` stored and why does it matter?

The pepper is stored in [`config.toml`](https://github.com/akitaonrails/ai-memory/blob/main/config.toml) next to your data directory and printed to stdout during initialization. It is used to derive per-user authentication tokens. The value is never committed to Git, ensuring cryptographic isolation between deployments.

### Can I initialize ai-memory without network access?

Yes. The `init` command requires no network connectivity, no external API calls, and no authentication tokens. This makes it ideal for air-gapped environments and automated provisioning systems.

### How do I move my ai-memory data directory after initialization?

Copy the directory contents to the new location, then use `ai-memory --data-dir <NEW_PATH>` for subsequent commands. Update any shell aliases or systemd units that reference the old path.