Directory Structure

The .nexuscore/ directory stores NexusCore's configuration, skills, memory, checkpoints, and credentials. It exists at two levels: user-level (global) and project-level (per workspace).

User-Level (~/.nexuscore/)

The user-level directory stores global configuration and data shared across all projects.

~/.nexuscore/
├── config.yaml          # User configuration (models, agent, tools, sync)
├── credentials          # Auth tokens — refresh token for Nexus Suite (mode 0600)
├── memory/              # Persistent memory store
│   ├── default.db       # Default memory profile
│   ├── work.db          # Custom memory profile
│   └── personal.db      # Custom memory profile
├── skills/              # Installed skills (from Skills Hub or manually added)
│   ├── code-reviewer/
│   │   ├── manifest.json
│   │   └── prompt.md
│   └── pr-reviewer/
│       ├── manifest.json
│       └── prompt.md
├── checkpoints/         # Saved workspace checkpoints (auto and manual)
│   ├── 2024-01-15T10-30-00/
│   │   ├── metadata.json
│   │   └── files/
│   └── 2024-01-15T11-00-00/
│       ├── metadata.json
│       └── files/
└── logs/                # Agent session logs
    └── 2024-01-15.log

Project-Level (.nexuscore/)

The project-level directory stores workspace-specific configuration and data. Place it in your project root.

my-project/
└── .nexuscore/
    ├── config.yaml      # Project-specific config overrides
    ├── mcp.json         # MCP server connections for this workspace
    ├── skills/          # Project-local skills (version-controlled)
    │   └── project-conventions/
    │       ├── manifest.json
    │       └── prompt.md
    └── memory/          # Project-scoped memory
        └── project.db

Project-level config overrides user-level config for that workspace. This is useful for:

• Setting project-specific model preferences
• Defining MCP server connections
• Sharing project-local skills with your team via version control

Key Files

config.yaml

The main configuration file. See CLI Configuration for the full format.

credentials

Stores the Nexus Suite refresh token for authenticated sessions. This file is created by nexus-cli auth login and has restricted permissions.

WARNING

Never commit credentials to version control. Add ~/.nexuscore/credentials to your global gitignore.

mcp.json

Defines MCP server connections for the workspace. See MCP Discovery for the format.

memory/*.db

SQLite databases storing the agent's persistent memory. Each file represents a memory profile (default, work, personal, or custom).

checkpoints/

Workspace checkpoints created automatically before agent file operations, or manually via the command palette. Each checkpoint contains metadata and copies of affected files.

File Permissions

File	Mode	Description
credentials	0600	Auth tokens — readable only by owner
config.yaml	0644	Configuration — readable by all
memory/*.db	0600	Memory databases — readable only by owner
logs/*.log	0600	Session logs — readable only by owner

Version Control

Recommended .gitignore entries

For your project's .gitignore:

# NexusCore local data
.nexuscore/memory/
.nexuscore/checkpoints/

For your global ~/.gitignore:

# NexusCore credentials
.nexuscore/credentials
.nexuscore/logs/

Files safe to commit

These project-level files are safe (and recommended) to commit:

• .nexuscore/config.yaml — Project-specific settings
• .nexuscore/mcp.json — MCP server connections
• .nexuscore/skills/ — Project-local skills