AI Agents & Chat

MemGhost includes an AI system that powers classification, hub pages, Spaces, semantic search, and chat agents. AI can run via cloud providers (OpenRouter, Anthropic) or locally via Ollama.

AI features are optional. MemGhost works without them — the vault, notes, and basic hub structure all function independently. AI adds classification, smart routing, page synthesis, Spaces, and chat.

AI Providers

MemGhost supports multiple AI providers. You can mix providers for different capabilities.

OpenRouter (Recommended)

A single API key gives access to multiple models for both chat and embeddings:

AI_ENABLED=true
AI_LLM_PROVIDER=openrouter
AI_LLM_API_KEY=sk-or-...
AI_EMBEDDING_PROVIDER=openrouter
AI_EMBEDDING_API_KEY=sk-or-...

Anthropic

Use Anthropic directly for chat. Requires a separate embedding provider (OpenRouter or Ollama):

AI_ENABLED=true
AI_LLM_PROVIDER=anthropic
AI_LLM_API_KEY=sk-ant-...
AI_EMBEDDING_PROVIDER=ollama
AI_EMBEDDING_BASE_URL=http://ollama:11434

Local Ollama

Run everything on your hardware with no cloud dependency. Requires a capable GPU for reasonable speed:

AI_ENABLED=true
AI_LLM_PROVIDER=ollama
AI_LLM_BASE_URL=http://ollama:11434
AI_LLM_MODEL=qwen3:8b
AI_EMBEDDING_PROVIDER=ollama
AI_EMBEDDING_BASE_URL=http://ollama:11434
AI_EMBEDDING_MODEL=nomic-embed-text

Required models (one-time download):

nomic-embed-text (~275 MB) — embeddings for semantic search and hub routing
qwen3:8b (~5 GB) — chat model for agents and hub pipeline

What AI Powers

Hub Pipeline

The core AI feature. When items enter the vault:

Classification — LLM identifies type, extracts tags and metadata
Routing — LLM assigns items to topic hubs using embedding search + graph context
Materialization — LLM synthesizes hub pages from source items into coherent prose

This turns a stream of fragments into an organized personal wiki.

Spaces

AI conversation workspaces with configurable personas. Each Space has living artifacts that persist across sessions and sync rules that publish outputs back to the vault. Templates include Therapy Practice, Homework Helper, Career Coach, and more.

Chat Interface

The chat UI lets you converse with AI agents that have tool access to your data via MCP (Model Context Protocol). Features:

Streaming responses — word-by-word as they’re generated
Tool use — agents can search your vault, read hub pages, manage artifacts
Session history — conversations are saved and can be resumed
Voice mode — when TTS is enabled, spoken responses (see Voice)

Semantic Search

MemGhost automatically generates vector embeddings for vault items (768-dimensional vectors stored in pgvector). This powers:

Natural-language search across all your data
Hub routing candidate selection
AI agent tool calls for finding relevant items

Tools and Services

Agents interact with MemGhost through a layered tool system:

Core Platform Tools

Every agent automatically receives discovery and creation tools:

Tool	What It Does
`browse_services`	Search all available RPC services
`browse_tools`	List available tools from all sources
`get_tool_source`	Read the source code of existing tools
`create_tool`	Write and test new tool compositions
`save_tool`	Save a working tool for reuse

Module Tools

Modules ship curated TypeScript tools that compose RPC service calls:

Module	Example Tools
Vault	Search vault items, get item details, capture new items
Note	Search notes, create/update notes, manage tags
Hubs	Read hub pages, edit hub pages, list child nodes
Spaces	Read/write artifacts, list artifacts, capture to vault
Setup	Check system status

Sandbox

When SANDBOX_ENABLED=true, agents can execute TypeScript code in a secure Deno subprocess. Tools use rpc() calls to interact with platform services.

Configuration

LLM

Variable	Default	Description
`AI_ENABLED`	`false`	Master toggle for all AI features
`AI_LLM_PROVIDER`	`ollama`	LLM provider (`ollama`, `openrouter`, `anthropic`)
`AI_LLM_BASE_URL`	`http://ollama:11434`	Provider API URL (for Ollama)
`AI_LLM_API_KEY`	(none)	API key (for OpenRouter or Anthropic)
`AI_LLM_MODEL`	`qwen3:8b`	Chat model name

Embeddings

Variable	Default	Description
`AI_EMBEDDING_PROVIDER`	`ollama`	Embedding provider (`ollama`, `openrouter`)
`AI_EMBEDDING_BASE_URL`	`http://ollama:11434`	Provider API URL
`AI_EMBEDDING_API_KEY`	(none)	API key (for OpenRouter)
`AI_EMBEDDING_MODEL`	`nomic-embed-text`	Embedding model
`AI_EMBEDDING_DIMENSIONS`	`768`	Vector dimensions (must match model)

Using a Different Local Model

Swap the chat model for any Ollama-compatible model:

docker compose exec ollama ollama pull llama3.1:8b
# Then update AI_LLM_MODEL in .env and restart

GPU Acceleration (Ollama)

For NVIDIA GPUs, update the Ollama service in your compose file:

ollama:
  image: docker.io/ollama/ollama:latest
  deploy:
    resources:
      reservations:
        devices:
          - driver: nvidia
            count: 1
            capabilities: [gpu]

Requires the NVIDIA Container Toolkit.