memories init

memories init [options]

Alias:

memories setup [options]

Initialize the memories database and automatically set up MCP integration for detected AI coding tools. This is the recommended first command after installing memories.sh.

What it does

Creates the local database at ~/.config/memories/local.db
Detects your project from the git remote URL (or sets global scope if not in a git repo)
Detects installed AI tools by checking for their config directories
Configures MCP for each detected tool (with your permission)
Generates instruction files (including a baseline harness when no memories exist yet)
Imports existing project skill configs (for example from .claude/skills, .codex/skills) into memories
Shows sync status if you're logged in

Options

Option	Description
`-g, --global`	Initialize global memories (apply to all projects)
`-r, --rule <rule>`	Add an initial rule (can be repeated)
`--mode <mode>`	Setup mode: `auto`, `local`, or `cloud`
`--scope <scope>`	Memory scope: `auto`, `project`, or `global`
`--skip-mcp`	Skip automatic MCP configuration
`--skip-generate`	Skip generating instruction files
`--skip-skill-ingest`	Skip importing existing project skills into memories
`--minimal-local`	Apply local-only setup preset (no cloud/workspace dependency checks)
`-y, --yes`	Auto-confirm all prompts

Setup mode

auto (default): prompts for local vs cloud guidance in interactive sessions
local: skips login/workspace provisioning prompts
cloud: runs guided login + workspace checks/provisioning
--minimal-local: forces local mode and local-only verification defaults

Memory scope

auto (default): choose interactively in TTY sessions, fallback to project when available
project: force project-scoped memories for this setup
global: force global-scoped memories for this setup

Detected Tools

The init command looks for these AI coding tools:

Tool	Detect Paths	MCP Config Location
Cursor	`.cursor/`	`.cursor/mcp.json`
Claude Code	`.claude/`, `CLAUDE.md`	`.mcp.json` (project root)
Windsurf	`.windsurf/`, `.windsurfrules`	`.windsurf/mcp.json`
VS Code	`.vscode/`	`.vscode/mcp.json`
OpenCode	`.opencode/`, `opencode.json`	`opencode.json` (project) / `~/.config/opencode/opencode.json` (global)
Factory	`.factory/`	`.factory/mcp.json`
Kiro	`.kiro/`, `.kiro/settings/mcp.json`	`.kiro/settings/mcp.json`
Kilo	`.kilo/`, `.kilo/mcp.json`	`.kilo/mcp.json`
Trae	`.trae/`, `.trae/mcp.json`	`.trae/mcp.json`
Antigravity	`.antigravity/`, `mcp_config.json`	`.antigravity/mcp.json` (project) / `~/.gemini/antigravity/mcp_config.json` (global)
Goose	`.goose/`	—
OpenClaw	`~/.openclaw/workspace/{AGENTS,SOUL,TOOLS,IDENTITY,USER,HEARTBEAT,BOOTSTRAP}.md`	—
Blackbox CLI	`blackbox` command	Managed by `blackbox mcp` commands
Amp	`.amp/`	`.amp/mcp.json`
Agents harness (.agents/Codex)	`.agents/`, `AGENTS.md`, `.codex/`	—
GitHub Copilot	`.github/copilot-instructions.md`	—
Gemini	`GEMINI.md`	—
Cline	`.clinerules/`	—
Roo	`.roo/`	—

For each detected tool, init will:

Check if MCP is already configured
Offer to add the memories MCP server if not
Generate instruction files when supported (or baseline harness files for new projects)

On first-time setup, init also offers global MCP onboarding so local and cloud IDE workflows can share the same memory layer.

Examples

Basic initialization

cd your-project
memories setup

Output:

[1/4] Setting up local storage...
  Database: ~/.config/memories/local.db
[2/4] Detecting scope...
✓ Project scope detected
  Project: github.com/your-org/your-project
[3/4] Detecting AI coding tools...
  Cursor ✓ MCP ○ Rules
  Claude Code ○ MCP ✓ Rules
  Windsurf [global] ○ MCP ○ Rules

? Configure MCP for Claude Code, Windsurf? (Y/n)
✓ Claude Code: MCP configured → .mcp.json
✓ Windsurf: MCP configured → ~/.windsurf/mcp.json

? Generate instruction files for Cursor? (Y/n)
✓ Cursor: Generated .cursor/rules/memories.mdc
[4/4] Finalizing...
✓ Syncing as you@example.com

Non-interactive mode

memories setup -y

Auto-confirms all prompts — useful for scripts or CI.

Skip automatic setup

# Only create database, don't configure tools or skill import
memories setup --skip-mcp --skip-generate --skip-skill-ingest

10-minute minimal local happy path

# Local-only setup with no cloud/workspace dependency
memories setup --minimal-local -y

# Verify local checks (cloud intentionally skipped)
memories doctor --local-only

# Confirm first memory round-trip
memories add --rule "Local setup smoke test"
memories search "Local setup smoke test"

Initialize with starter rules

memories setup \
  --rule "Use TypeScript strict mode" \
  --rule "Prefer functional components" \
  --rule "Use pnpm as package manager"

Global initialization

memories setup --global

Useful when not in a git repository, or when you want to set up memories that apply to all projects.

MCP Configuration

When init configures MCP, it adds this to each tool's config:

{
  "mcpServers": {
    "memories": {
      "command": "npx",
      "args": ["-y", "@memories.sh/cli", "serve"]
    }
  }
}

Using npx ensures the latest version is always used. If you installed memories globally, the tool will use your global installation.

After Init

Once initialized, you can:

# Add your first memory
memories add --rule "Always use early returns"

# Regenerate instruction files
memories generate all

# Search your memories
memories search "authentication"

# Start syncing to cloud
memories login

On this page