Can ai-memory Function Without an LLM Provider Configured? Understanding Zero-LLM Mode

Yes, ai-memory functions fully without an LLM provider by running in Zero-LLM mode, where core features like FTS5 search and wiki storage remain active while LLM-specific capabilities are gracefully disabled.

The akitaonrails/ai-memory repository is architected to operate independently of large language model integrations. When no provider is configured, the system defaults to Zero-LLM mode, delivering persistent storage and full-text search capabilities without requiring API keys or external AI services.

What Is Zero-LLM Mode?

Zero-LLM mode is the default operational state of ai-memory. According to the project's architecture documentation, the system follows a "Zero-LLM default path" where the LLM has "opt-in via env" (see docs/ARCHITECTURE.md, line ~479). This design philosophy ensures that the core engine remains lightweight and functional even when LLM access is unavailable, restricted, or undesired.

The README confirms this behavior explicitly: "LLM is opt-in. Zero-LLM mode still gives you FTS5, manually declared" (see README.md, line ~189). The binary compiles and launches successfully regardless of whether LLM environment variables are present.

Core Features Available Without an LLM Provider

When running ai-memory without an LLM provider configured, you retain full access to the foundational knowledge management stack:

• Persistent Storage – Create and manage projects with durable data retention
• FTS5 Full-Text Search – Query your markdown wiki using the built-in SQLite FTS5 engine
• Markdown Wiki Handling – Write, edit, and organize pages in standard markdown format
• Agent-Hook Pipeline – Execute automation workflows that don't require natural language generation

These capabilities function entirely within the local database layer, requiring no network calls to external AI services.

What Requires an LLM Provider?

Certain advanced features remain dormant in Zero-LLM mode until you configure a provider via environment variables (e.g., AI_MEMORY_LLM_PROVIDER). Attempting to invoke these commands returns a clear configuration error:

• Embedding Generation – The ai-memory embed command requires a vectorization model
• Auto-Improvement – The ai-memory auto-improve feature needs LLM reasoning capabilities
• Automatic Consolidation – Background processes that summarize or refactor content remain suspended

The system validates LLM configuration at the CLI entry point in crates/ai-memory-cli/src/main.rs, gracefully routing commands to the optional LLM subsystem implemented in crates/ai-memory-llm/src/lib.rs only when the relevant environment variables are detected.

How Zero-LLM Mode Works Under the Hood

The architecture separates core storage logic from LLM abstractions. When the CLI launches via main.rs, it parses environment configuration; without AI_MEMORY_LLM_… variables present, the initialization routine in crates/ai-memory-llm/src/lib.rs skips provider instantiation entirely.

This modular design means:

• The SQLite-backed storage layer initializes unconditionally
• The FTS5 virtual tables are created and indexed regardless of AI configuration
• The agent pipeline executes hooks that don't specify LLM dependencies

Only when a command specifically requests LLM capabilities does the system check for the provider and return an error if absent.

Practical Examples: Running ai-memory Without LLM Configuration

You can start using ai-memory immediately after installation without any API keys:

# Initialize a new knowledge base

$ ai-memory init my-project
Successfully created project 'my-project'

# Write content using standard markdown

$ ai-memory write-page intro.md "Hello world"
Page 'intro.md' created in project 'my-project'

# Search using native FTS5 indexing

$ ai-memory search "Hello"
Found 1 result:
- intro.md: "Hello world"

Attempting LLM-dependent operations fails with a descriptive error:

$ ai-memory embed "some text"
error: LLM provider not configured – set AI_MEMORY_LLM_PROVIDER env var

From a programmatic perspective, the Rust initialization remains identical:

fn main() {
    // The CLI parses config at startup; without AI_MEMORY_LLM_… env vars
    // the LLM subsystem stays inactive.
    ai_memory_cli::run(); // core features work (storage, search, wiki)
}

Summary

• ai-memory defaults to Zero-LLM mode when no provider is configured, functioning as a standalone knowledge management system
• Core capabilities including FTS5 search, markdown wiki handling, and persistent storage operate without external dependencies
• LLM-specific features like embedding generation and auto-improvement are disabled until you set the appropriate environment variables
• The architecture in crates/ai-memory-llm/src/lib.rs implements the provider as an optional abstraction, ensuring the CLI in crates/ai-memory-cli/src/main.rs launches successfully regardless of AI configuration

Frequently Asked Questions

Does ai-memory crash if I don't configure an LLM provider?

No. The system is explicitly designed to start without LLM configuration. The binary initializes the storage engine and FTS5 modules by default, allowing immediate use of wiki and search features. Only commands that explicitly require LLM functionality will return an error indicating the missing provider.

Can I switch from Zero-LLM mode to LLM-enabled mode without losing data?

Yes. Adding an LLM provider via environment variables (such as AI_MEMORY_LLM_PROVIDER) enables advanced features on your existing projects without affecting your stored data. The persistent storage layer remains compatible across both operational modes.

Which commands require an LLM provider to function?

Commands that involve semantic understanding or generation require configuration: ai-memory embed for vectorization, ai-memory auto-improve for content enhancement, and any consolidation or summarization routines. All project management, markdown editing, and FTS5 search commands function without LLM access.

Is there a faster performance when running ai-memory in Zero-LLM mode?

Zero-LLM mode eliminates network latency and API call overhead associated with external LLM providers. Since embedding generation and auto-improvement processes are disabled, the system consumes fewer computational resources and operates entirely on local SQLite transactions, resulting in faster response times for core storage and retrieval operations.

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