# How to Write Durable Wiki Knowledge with ai-memory: A Complete Guide

> Learn to write durable wiki knowledge with ai-memory. This guide details how ai-memory ensures data integrity through version control, atomic writes, and indexing for reliable knowledge management.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-09-09

---

**ai-memory stores every piece of knowledge as a version-controlled markdown file using atomic write-to-disk operations, SQLite indexing, and admission sanitization to guarantee durability.**

The ai-memory project by akitaonrails treats AI knowledge as durable wiki pages stored in a hierarchical markdown file system. When you write durable wiki knowledge with ai-memory, every page persists to disk inside `<data_dir>/wiki/<workspace>/<project>/<path>.md` while maintaining a synchronized search index. This architecture ensures your knowledge survives crashes, supports version control via git, and remains instantly searchable.

## The Three Layers of Durability

### Atomic Write-to-Disk Operations

According to [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs) (lines 24-33), the `Wiki::write_page` method implements atomic persistence by writing to a temporary file first, then replacing the target with `rename` and `fsync`. This guarantees that a page is either fully persisted to disk or not written at all, preventing corruption from partial writes or mid-process crashes.

### Single-Writer SQLite Actor

The same function upserts a row for the new page version in the SQLite store inside the same transaction (lines 52-71). This ensures the markdown file and the search index stay perfectly synchronized. If the process crashes after the file write but before the transaction commits, the database remains consistent with the filesystem state.

### Admission and Sanitization Pipeline

Before any content hits the filesystem, the body and front-matter pass through a sanitization layer (lines 60-82). This pipeline scrubs secrets, stamps the content with the authenticated actor's ID, and optionally routes through configurable admission webhooks for validation.

## Entry Points for Writing Wiki Pages

### CLI Command (ai-memory write-page)

The most common way to write durable wiki knowledge with ai-memory is through the CLI. Located at [`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) (lines 42-74), the `write-page` command reads arguments including workspace, project, path, and body, then POSTs a JSON payload to the server's `POST /admin/write-page` endpoint. The resolver automatically infers workspace and project from the current directory if not explicitly provided (lines 53-58).

### MCP Tool (memory_write_page)

For AI agents and automated systems, the `memory_write_page` tool defined in [`crates/ai-memory-mcp/src/server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs) (lines 2887-2902) offers direct programmatic access. This MCP tool constructs the same JSON payload as the CLI and sends it to the identical admin route, making it seamless for agents to persist knowledge without shelling out to the CLI.

### Direct Rust API

Internal code and tests call `Wiki::write_page` directly ([`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs), lines 33-41). This bypasses the HTTP layer but executes the full admission, sanitization, and atomic-write logic, making it ideal for high-performance batch operations or custom integrations.

## Step-by-Step Workflow to Create Durable Pages

1. **Select Workspace and Project.** Either pass `--workspace` and `--project` flags explicitly or let the CLI infer them from your current directory. The resolver guarantees that subsequent read and search commands target the same project context.

2. **Compose Front-Matter.** Define metadata including `title`, `kind`, `tier`, `tags`, and `pinned`. The system automatically adds `last_modified_by` (the authenticated actor) and canonicalizes boolean fields like `pinned` ([`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs), lines 68-78).

3. **Send the Write Request.** The CLI reads the body from stdin (`-`) or a literal string, builds a `WritePageBody` struct, and POSTs it. The handler at [`crates/ai-memory-mcp/src/admin.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/admin.rs) (lines 6469-6486) validates the request, runs sanitization, executes admission webhooks, atomically writes the file, and updates the SQLite index ([`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), lines 59-77).

4. **Verify Durability.** The server responds with the new `page_id` and full filesystem path. You can immediately read the page back using `ai-memory read-page` or search via `ai-memory search`. Because the write uses atomic file replacement, the page exists in both the on-disk wiki and the index even if the server crashes immediately after responding (lines 78-82).

## Practical Examples

### CLI Usage

```bash
ai-memory write-page \
  --workspace default \
  --project my-project \
  --path notes/ai-memory.md \
  --title "Durable wiki knowledge with ai-memory" \
  --tier "knowledge" \
  --tag ai-memory --tag wiki \
  --pinned \
  --body "This page demonstrates how to store durable wiki knowledge using ai-memory."

```

### HTTP API Usage

```http
POST /admin/write-page HTTP/1.1
Host: localhost:49374
Content-Type: application/json
Authorization: Bearer <token>

{
  "workspace":"default",
  "project":"my-project",
  "path":"notes/ai-memory.md",
  "body":"This page demonstrates how to store durable wiki knowledge using ai-memory.",
  "title":"Durable wiki knowledge with ai-memory",
  "kind":"article",
  "tier":"knowledge",
  "tags":["ai-memory","wiki"],
  "pinned":true
}

```

### Rust API Usage

```rust
use ai_memory_wiki::{Wiki, WritePageRequest};

let wiki = Wiki::new(...); // constructed with data_dir, git, etc.
let req = WritePageRequest {
    workspace_id: "default".into(),
    project_id: "my-project".into(),
    path: "notes/ai-memory.md".into(),
    frontmatter: serde_json::json!({
        "title": "Durable wiki knowledge with ai-memory",
        "tier": "knowledge",
        "tags": ["ai-memory", "wiki"],
        "pinned": true
    }),
    body: "This page demonstrates how to store durable wiki knowledge using ai-memory.".into(),
    tier: "knowledge".into(),
    pinned: true,
    title: None,
    admission_ctx: None,
    author_id: None,
    actor: Default::default(),
};
let page_id = wiki.write_page(req).await?;
println!("Wrote page id {}", page_id);

```

## Summary

- **Atomic durability**: ai-memory uses temporary files with rename/fsync operations in `Wiki::write_page` to guarantee pages are either fully written or not written at all.
- **Synchronized indexing**: Every page write updates both the markdown file hierarchy and the SQLite index in a single transaction, preventing drift between storage layers.
- **Multiple interfaces**: Write durable wiki knowledge via the `ai-memory write-page` CLI, the `memory_write_page` MCP tool, or the direct Rust API depending on your integration needs.
- **Sanitization by default**: All content passes through admission pipelines that scrub secrets and validate metadata before persistence.
- **Version control ready**: Pages reside in `<data_dir>/wiki/<workspace>/<project>/<path>.md`, making them compatible with git workflows for audit trails and rollback.

## Frequently Asked Questions

### What happens if the ai-memory server crashes during a write operation?

Because `Wiki::write_page` writes to a temporary file first and uses atomic rename operations ([`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs), lines 24-33), the target file remains unchanged if the process crashes mid-write. Additionally, the SQLite upsert occurs in the same logical transaction, ensuring the index and filesystem stay synchronized even after unexpected failures.

### Can I use ai-memory to write wiki pages from languages other than Rust?

Yes. While the Rust API offers the most direct integration, you can write durable wiki knowledge using the HTTP API by POSTing to `/admin/write-page` with a JSON payload matching the `WritePageBody` schema. The CLI also supports stdin input, allowing shell scripts in any language to pipe content into `ai-memory write-page`.

### How does ai-memory handle concurrent writes to the same wiki page?

The single-writer SQLite actor design serializes write operations through the database transaction layer ([`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs), lines 52-71). This prevents race conditions when multiple agents or CLI processes attempt to modify the same `<workspace>/<project>/<path>` simultaneously, ensuring each write is atomic and ordered.

### What metadata fields are required when writing a new page?

Only `workspace`, `project`, and `path` are strictly required to locate the file. However, effective durable wiki knowledge management typically includes `title`, `tier` (e.g., "knowledge", "task"), and `tags` for organization. The system automatically injects `last_modified_by` and timestamps, while optional fields like `pinned` and `kind` help with prioritization and categorization.