How to Manually Write a Permanent Decision Page in ai-memory

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 <project-root>/wiki, though the exact path may vary based on your .ai-memory.toml marker file location. Confirm your current wiki location by running:

ai-memory status

If the decisions/ subdirectory does not exist beneath the wiki root, create it manually:

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, handles directory creation and opens your default editor:

ai-memory write-page --path decisions/choose-json-library.md

When the editor opens, prepend the mandatory frontmatter to mark the page as permanent:

---
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/<slug>.md using any text editor. The file must begin with the permanent tier declaration:

---
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 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:

ai-memory lint --path decisions/choose-json-library.md

Test discoverability by querying the knowledge base:

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, 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:

# 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:

---
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:

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: 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: Implements atomic write logic ensuring frontmatter parsing and safe persistence.
• crates/ai-memory-cli/src/commands/write_page.rs: Provides the write-page command interface with automatic directory creation.
• docs/marker-file.md: Explains wiki root discovery via .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 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, ensures that even during system crashes, you will never have a partially written or corrupted decision file.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}