Skip to main content
A space in Glyph is a directory-based workspace that contains all your notes, assets, and metadata. Each space is a self-contained environment with its own search index, settings, and organization.

​
What is a Space?

A space is simply a folder on your computer that Glyph uses to store and organize your notes. When you create or open a space, Glyph sets up a special .glyph/ directory inside it to store metadata, cache, and app-specific data.

​
Directory Structure

When you create a space, Glyph automatically creates this structure: 
your-space/
├── .glyph/
│   ├── glyph.sqlite       # Search index database
│   ├── cache/             # Cached assets and data
│   └── Glyph/
│       └── ai_history/    # AI conversation history
├── notes/                 # Your markdown files (optional)
├── assets/                # Images, attachments (optional)
└── (your files and folders)
The .glyph/ folder stores all metadata and should not be manually edited. It’s automatically managed by the app.

​
Creating a Space

You can create a new space in two ways:
  1. From the Welcome Screen: Click “Create Space” and choose a directory
  2. From the Menu: Navigate to File → Create Space (or use Cmd+Shift+N on macOS)
When you create a space, Glyph:
  • Creates the .glyph/ directory structure
  • Initializes the search database
  • Sets up the file watcher for real-time updates
  • Cleans up any temporary files from previous sessions
// From src-tauri/src/space/helpers.rs
pub fn create_or_open_impl(root: &Path) -> Result<SpaceInfo, String> {
    ensure_glyph_dirs(root)?;
    let _ = cleanup_tmp_files(root);
    Ok(SpaceInfo {
        root: root.to_string_lossy().to_string(),
        schema_version: VAULT_SCHEMA_VERSION,
    })
}

​
Opening a Space

To open an existing space:
  1. Use Cmd+O (macOS) or Ctrl+O (Windows/Linux)
  2. Select the folder containing your notes
  3. Glyph will detect if it’s an existing space or create a new one
When you open a space, Glyph performs these operations:
  1. Validates the directory - Ensures it’s a valid folder path
  2. Initializes metadata - Creates .glyph/ structure if needed
  3. Starts file watcher - Monitors changes to your files in real-time
  4. Loads the index - Opens the SQLite database for search
  5. Cleans temporary files - Removes .tmp files from crashes
The file watcher (implemented in src-tauri/src/space/watcher.rs) monitors all changes and updates the search index automatically with a 100ms debounce.

​
File Watching

Glyph monitors your space directory for changes using a recursive file watcher. This means:
  • Real-time updates: Changes from external editors appear immediately
  • Smart indexing: Only modified files are re-indexed
  • Change debouncing: Multiple rapid changes are batched (100ms window)
  • Hidden file filtering: Ignores files/folders starting with .

​
How It Works

// From src-tauri/src/space/watcher.rs
const DEBOUNCE_MS: u64 = 100;

// The watcher monitors three types of events:
// - Create: New files or folders
// - Modify: Content changes
// - Remove: Deleted files or folders
When changes are detected:
  1. External changes trigger a space:fs_changed event to the frontend
  2. Markdown files are automatically re-indexed for search
  3. The file tree UI updates to reflect changes
  4. Recent local changes (within 2 seconds) are tracked to avoid duplicate processing
Glyph ignores its own writes for 2 seconds to prevent re-indexing files you just saved.

​
Closing a Space

To close the current space:
  • Use File → Close Space from the menu
  • The file watcher stops
  • The search index connection closes
  • Recent spaces list is updated
Your files remain untouched - closing a space just disconnects Glyph from monitoring it.

​
Recent Spaces

Glyph remembers recently opened spaces for quick access. You can:
  • View recent spaces in Settings → Space
  • Clear the recent list with the “Clear” button
  • Reopen a recent space from the welcome screen

​
Space Operations Reference

​
Best Practices

  1. Keep spaces focused: Create separate spaces for different projects or areas
  2. Use cloud sync carefully: If syncing with Dropbox/iCloud, exclude .glyph/cache/
  3. Don’t nest spaces: Avoid creating one space inside another
  4. Backup regularly: The .glyph/ folder can be recreated, but back up your notes
Yes! You can version control your space with Git. Consider adding this to .gitignore:
.glyph/cache/
.glyph/*.tmp
The search database (glyph.sqlite) can be committed or ignored - Glyph will rebuild it if missing.

​
Troubleshooting

​
Space won’t open

  • Ensure the folder exists and you have read/write permissions
  • Check that the path doesn’t contain special characters
  • Try creating a new space instead

​
Search not working

  • Go to Settings → Space and click “Rebuild Index”
  • This re-indexes all markdown files in your space

​
Changes not appearing

  • The file watcher may have stopped - try closing and reopening the space
  • Check that changed files aren’t in hidden folders (starting with .)