# How to Manually Write a Permanent Decision Page in ai-memory > Learn to manually write a permanent decision page in ai-memory. Create a markdown file in wiki/decisions/ with tier permanent frontmatter for lasting records. - Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory) - Tags: how-to-guide - Published: 2026-08-31 --- **You can manually write a permanent decision page by creating a markdown file in the `wiki/decisions/` directory with `tier: permanent` frontmatter, ensuring it persists unchanged through AI consolidation cycles.** The `akitaonrails/ai-memory` project maintains project knowledge in a plain-markdown wiki stored within the `.ai-memory` directory. When you need to record stable architectural decisions or policies that must survive future AI session consolidations, you manually write a permanent decision page to immutably capture these conclusions. ## Locate the Wiki Root and Decisions Directory Permanent decision pages live in a specific namespace within the ai-memory wiki structure. Before creating content, identify where your project stores its knowledge base. The wiki root resides at `/wiki`, though the exact path may vary based on your [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) marker file location. Confirm your current wiki location by running: ```bash ai-memory status ``` If the `decisions/` subdirectory does not exist beneath the wiki root, create it manually: ```bash mkdir -p wiki/decisions ``` Alternatively, using the CLI command `ai-memory write-page` automatically creates missing directories during the write process. ## Create the Permanent Decision Page You have two methods to write a permanent decision page: direct file editing or the CLI tool. Both approaches produce identical results when you include the required frontmatter. ### Method 1: Using the CLI Write Command The `ai-memory write-page` command, implemented in [`crates/ai-memory-cli/src/commands/write_page.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/write_page.rs), handles directory creation and opens your default editor: ```bash ai-memory write-page --path decisions/choose-json-library.md ``` When the editor opens, prepend the mandatory frontmatter to mark the page as permanent: ```yaml --- tier: permanent tags: [library, json, rust] --- ``` Follow this header with your decision rationale, references, and detailed explanation. ### Method 2: Manual File Creation Create the file directly at `wiki/decisions/.md` using any text editor. The file must begin with the permanent tier declaration: ```markdown --- tier: permanent tags: [architecture, policy] --- # Decision: Adopt async/await for I/O operations We evaluated raw futures, tokio, and async-std. Based on ecosystem maturity and performance benchmarks, we standardize on tokio for all async runtime needs. ``` The [`crates/ai-memory-wiki/src/write.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/write.rs) module implements atomic file writes using `tmp + rename + fsync` to prevent corruption during persistence. ## Validate and Commit Your Decision After writing the file, verify it conforms to the wiki schema using the lint command: ```bash ai-memory lint --path decisions/choose-json-library.md ``` Test discoverability by querying the knowledge base: ```bash ai-memory query "choose-json-library" ``` Commit the new file to version control. While ai-memory uses atomic writes for file safety, git provides the authoritative history for your decision audit trail. ## Why the Permanent Tier Protects Your Content During consolidation, the LLM merges session observations into existing wiki pages. According to [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md), the Authority-aware recall system excludes pages marked with `tier: permanent` from the merge pipeline. This immutability guarantee ensures that strategic decisions, API contracts, or architectural policies remain exactly as you authored them, regardless of subsequent AI sessions or automated consolidations. ## Complete Implementation Example Here is a full workflow demonstrating the CLI approach: ```bash # Navigate to project root cd /path/to/my/project # Create decision via CLI (opens editor automatically) ai-memory write-page --path decisions/database-selection.md ``` In the editor, enter: ```markdown --- tier: permanent tags: [database, postgres, mysql] --- # Decision: Use PostgreSQL for Primary Data Store After evaluating SQLite, MySQL, and PostgreSQL against our consistency and scalability requirements, we standardize on PostgreSQL 15+. Rationale: - ACID compliance for financial transaction records - Native JSONB support for flexible metadata - Proven replication mechanisms for high availability This decision is permanent and revisable only through explicit architectural review. ``` Validate and verify: ```bash ai-memory lint --path decisions/database-selection.md ai-memory query "database-selection" ``` ## Key Source Files and Implementation Details Understanding these components deepens your knowledge of the persistence mechanism: - **[`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md)**: Documents the wiki layout, the decisions namespace, and the `tier: permanent` mechanism that protects against overwrites during consolidation. - **[`crates/ai-memory-wiki/src/write.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/write.rs)**: Implements atomic write logic ensuring frontmatter parsing and safe persistence. - **[`crates/ai-memory-cli/src/commands/write_page.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/write_page.rs)**: Provides the `write-page` command interface with automatic directory creation. - **[`docs/marker-file.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/marker-file.md)**: Explains wiki root discovery via [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) markers and distinguishes global versus project-scope pages. ## Summary - **Permanent decision pages** require the `tier: permanent` frontmatter flag to survive AI consolidation cycles. - Store these files in the `wiki/decisions/` directory, either manually or using `ai-memory write-page`. - Validate new pages with `ai-memory lint` before committing to ensure schema compliance. - The atomic write implementation in [`write.rs`](https://github.com/akitaonrails/ai-memory/blob/main/write.rs) guarantees file integrity during persistence. - Version control your decisions alongside the wiki files to maintain a complete audit history. ## Frequently Asked Questions ### What happens if I forget to include the permanent tier in my decision page? Without `tier: permanent`, the page becomes mutable during the next consolidation cycle. The LLM may merge new observations into your decision text, potentially altering or expanding your original conclusions. Always include the permanent tier tag for stable architectural records. ### Can I convert an existing regular wiki page into a permanent decision? Yes. Edit the existing markdown file to add `tier: permanent` to the frontmatter header. Once committed, the consolidation pipeline will exclude this page from future merges, treating all existing content as immutable. Run `ai-memory lint` after modification to verify the schema. ### Does ai-memory support permanent decisions outside the `decisions/` folder? While technically possible by placing `tier: permanent` frontmatter in any wiki file, the `decisions/` namespace is the conventional and recommended location. This separation ensures logical organization and signals to other developers that these files contain authoritative project policies. ### How does the atomic write mechanism protect my decisions? The system writes content to a temporary file, flushes to disk with `fsync`, then renames the temporary file to the target location. This sequence, implemented in [`crates/ai-memory-wiki/src/write.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/write.rs), ensures that even during system crashes, you will never have a partially written or corrupted decision file.