Botmem

Personal Memory for AI Agents — self-hosted, cross-modal, yours.

Botmem ingests events from your email, messages, photos, and locations — normalizes them into a unified memory schema — and provides cross-modal retrieval with weighted ranking. Your AI agents get a queryable personal memory layer. You keep full ownership of your data.

Features

• Semantic + keyword search — PostgreSQL full-text retrieval blended with pgvector similarity
• 7 connectors — Gmail, Slack, WhatsApp, iMessage, Photos/Immich, Locations/OwnTracks, Telegram
• Agent API + CLI — botmem search, botmem ask for humans and AI agents
• AES-256-GCM encryption — credentials and PII encrypted at rest with a recovery key
• Connector SDK — build your own connectors with @botmem/connector-sdk
• Automatic contact resolution — deduplicates people across all data sources
• Memory graph — related memories linked by semantic similarity

Quick Start

Docker (recommended)

git clone https://github.com/botmem/botmem.git
cd botmem
cp .env.example .env          # Configure environment (edit as needed)
docker compose pull            # Pull the latest API + app images
docker compose up -d           # Starts the app on http://localhost:12412

Next: You'll need Ollama with models pulled before your first sync. See the full Quick Start guide for AI backend setup, account creation, and first sync.

Development

Requires Node.js 20+, pnpm 9.15+, and Docker.

git clone https://github.com/botmem/botmem.git
cd botmem
docker compose up -d postgres redis             # Infrastructure only
pnpm install
cp .env.example .env
pnpm dev                      # API + web on http://localhost:12412

Production

cp .env.example .env.prod     # Edit with production secrets
cp Caddyfile.example Caddyfile # Edit with your domain
docker compose -f docker-compose.prod.yml up -d

You'll need to generate secrets (openssl rand -base64 48), configure your domain in the Caddyfile, and set up Ollama. See the deployment guide for full instructions.

Architecture

graph LR
    C[Connectors] -->|raw events| SQ[Sync Queue]
    SQ --> CQ[Clean Queue]
    CQ --> EQ[Embed Queue]
    EQ -->|vectors + records| PG[(PostgreSQL + pgvector)]
    EQ --> FQ[File Queue]
    FQ -->|VL/OCR| EQ
    EQ --> NQ[Enrich Queue]
    NQ -->|entities, links| PG
    CLI --> PG
    Web[Web UI] --> API[NestJS API]
    API --> PG

Connectors

CLI

# Search memories
npx botmem search "meeting with Sarah about Q3 budget"

# Ask a question (RAG)
npx botmem ask "What did John say about the project deadline?"

# JSON output for agents
npx botmem search "travel plans" --json

Monorepo Structure

apps/
  api/             NestJS 11 backend (REST + WebSocket)
  web/             React 19 + React Router 7 + Tailwind 4
packages/
  cli/             CLI tool (botmem)
  connector-sdk/   BaseConnector + ConnectorRegistry
  connectors/      Gmail, Slack, WhatsApp, iMessage, Immich, OwnTracks, Telegram
  shared/          Cross-layer types

Stack

Backend: NestJS 11, Drizzle ORM, PostgreSQL + pgvector, BullMQ/Redis AI: Ollama (default) or OpenRouter — swappable via AI_BACKEND env var Frontend: React 19, Vite 6, Zustand 5, Tailwind 4 Tooling: pnpm workspaces, Turborepo, Vitest, Husky

Documentation

Full docs at docs.botmem.xyz:

• Quick Start
• Configuration
• Agent API & CLI
• Architecture
• Building a Connector

Contributing

See CONTRIBUTING.md for development setup, PR process, and guidelines.

License

AGPL-3.0