# Recommended Directory Structure for Integrating RIME Grammar (.gram) Files: Complete Setup Guide

> Learn the recommended directory structure for RIME grammar files. This guide shows you where to place your .gram file for seamless integration with your input method.

- Repository: [amzxyz/rime-lmdg](https://github.com/amzxyz/rime-lmdg)
- Tags: how-to-guide
- Published: 2026-02-24

---

**Place the `wanxiang-lts-zh-hans.gram` file in your RIME user directory alongside your schema YAML files and enable the octagram module with the correct language identifier in your schema configuration.**

The `amzxyz/rime-lmdg` repository provides a high-quality n-gram language model for RIME input methods. Understanding the recommended directory structure for integrating this RIME grammar file ensures the octagram module correctly loads the statistical model for enhanced input prediction.

## Understanding the RIME Grammar Model Architecture

### The Generated .gram File

According to the source code in `语法模型构建.py` (lines 293-304), the build process generates a file named `wanxiang-lts-zh-hans.gram`. This binary grammar model contains the n-gram statistics that power contextual suggestions. The [`wanxiang-tools.py`](https://github.com/amzxyz/rime-lmdg/blob/main/wanxiang-tools.py) file (line 89) defines this filename as a constant: `MODEL_FILE = "wanxiang-lts-zh-hans.gram"`, ensuring consistency across the toolchain.

### Directory Placement Requirements

RIME requires the `.gram` file to reside in the **user directory** at the same level as your schema definition files (`*.yaml`). The engine loads grammar models by resolving the `language` parameter in the octagram configuration against files in this directory. Unlike dictionary files that might live in subdirectories, grammar models must sit at the root of the user configuration folder.

## Step-by-Step Integration Guide

### 1. Obtain the Grammar Model

You have two primary methods to acquire the `.gram` file according to the repository source:

**Option A: Download Pre-built Release**

Use [`scripts/fetch_any_dict.py`](https://github.com/amzxyz/rime-lmdg/blob/main/scripts/fetch_any_dict.py) (lines 800-801) to automatically download the latest release:

```python
from pathlib import Path
from scripts.fetch_any_dict import download_dict

rime_dir = Path.home() / ".config" / "ibus" / "rime"
download_dict(
    url_dict=None,
    out_url_directory=rime_dir,
    is_download_gram=True  # Target only the .gram file

)

```

**Option B: Build from Source**

Run the generation script to create the grammar model locally:

```bash
python 语法模型构建.py

```

This executes the build logic defined at lines 293-304 of `语法模型构建.py`, producing `wanxiang-lts-zh-hans.gram` in your current working directory.

### 2. Position the File in RIME User Directory

Move or copy the generated/downloaded file to your platform-specific RIME user directory:

- **Windows**: `%APPDATA%\Rime\` (typically `C:\Users\<Username>\AppData\Roaming\Rime\`)
- **macOS**: `~/Library/Rime/` or `~/.config/ibus/rime/` depending on frontend
- **Linux**: `~/.config/ibus/rime/` or `~/.local/share/fcitx5/rime/`

The file must sit **at the root level** alongside your [`default.custom.yaml`](https://github.com/amzxyz/rime-lmdg/blob/main/default.custom.yaml) and schema files:

```text
~/.config/ibus/rime/
├── wanxiang-lts-zh-hans.gram    # Grammar model (root level)

├── wanxiang.schema.yaml         # Schema definition

└── default.custom.yaml          # Custom configuration

```

### 3. Enable Octagram in Schema Configuration

In your schema YAML file (e.g., [`wanxiang.schema.yaml`](https://github.com/amzxyz/rime-lmdg/blob/main/wanxiang.schema.yaml)), include the octagram module and specify the language identifier matching your `.gram` filename (minus the extension):

```yaml
__include: octagram   # Enable grammar model support

octagram:
  __patch:
    grammar:
      language: wanxiang-lts-zh-hans  # Matches .gram filename without extension

      collocation_max_length: 7
      collocation_min_length: 2
      collocation_penalty: -10
      non_collocation_penalty: -20
      weak_collocation_penalty: -35
      rear_penalty: -12
    translator/contextual_suggestions: false
    translator/max_homophones: 5
    translator/max_homographs: 5

```

## Automated Deployment with sync_rime.py

For users maintaining multiple installations, the repository provides [`scripts/sync_rime.py`](https://github.com/amzxyz/rime-lmdg/blob/main/scripts/sync_rime.py), which automates the download and placement process:

```bash
python scripts/sync_rime.py

```

This script handles the directory detection and file placement automatically, ensuring the `wanxiang-lts-zh-hans.gram` file lands in the correct location regardless of your operating system.

## Critical Compatibility Considerations

According to the project [`README.md`](https://github.com/amzxyz/rime-lmdg/blob/main/README.md), **do not enable both octagram and cloud plugins simultaneously**. RIME frontends like Weasel (Windows) or Squirrel (macOS) cannot load both modules concurrently. Choose either the local grammar model via octagram **or** the cloud prediction service, but never both, or the grammar model will fail to initialize.

## Summary

- **Obtain** the `wanxiang-lts-zh-hans.gram` file via [`fetch_any_dict.py`](https://github.com/amzxyz/rime-lmdg/blob/main/fetch_any_dict.py) or `语法模型构建.py`
- **Place** the file in your RIME user directory root (same level as schema YAMLs)
- **Configure** `__include: octagram` in your schema with `language: wanxiang-lts-zh-hans`
- **Avoid** using cloud plugins concurrently with octagram
- **Restart** your input method to load the grammar model into memory

## Frequently Asked Questions

### Where exactly do I place the .gram file on Windows?

Place `wanxiang-lts-zh-hans.gram` directly in `%APPDATA%\Rime\` (resolve to `C:\Users\<YourName>\AppData\Roaming\Rime\`). The file must sit at the root of this directory, not inside subfolders like `build/` or `luna_pinyin.userdb/`, for RIME to resolve the grammar reference.

### Can I rename the .gram file to something else?

While technically possible if you modify [`wanxiang-tools.py`](https://github.com/amzxyz/rime-lmdg/blob/main/wanxiang-tools.py) (line 89), it is **not recommended**. The octagram configuration uses the `language` parameter to construct the filename lookup. If you rename the file, you must update the `language:` value in your schema YAML to match exactly (without the `.gram` extension).

### Why is my grammar model not loading after placement?

First, verify the file is in the correct directory (same level as your active schema). Second, confirm you have included `__include: octagram` in your schema YAML and that the `language:` parameter matches the filename. Finally, ensure you are not running a cloud plugin simultaneously, as noted in the [`README.md`](https://github.com/amzxyz/rime-lmdg/blob/main/README.md), which prevents octagram initialization.

### How do I verify the grammar model is active during typing?

After deployment and restarting RIME, type phrases that require contextual disambiguation. With `collocation_max_length` set in your octagram configuration (as shown in lines 293-304 of the build script documentation), you should observe improved prediction for multi-character collocations. Check your RIME log files if suggestions fail to appear, as they will report grammar loading errors.