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

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 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 — 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

ai-memory init

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

Custom Data Directory

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

# 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), 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) 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) 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), the configuration logic:

• Generates a random token_pepper if missing
• Writes 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

---

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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}