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

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

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

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

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

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