AI-Memory — Documentation

AI-Memory is a self-hosted, shared knowledge memory for Claude Code and other LLM workflows. It exposes your team's notes and documents to AI assistants on-demand through an MCP server, using hybrid search (vector + keyword) so the assistant pulls only the few relevant snippets instead of loading everything — saving tokens and keeping answers grounded in your own knowledge.

It ships as a Docker Compose stack you run on your own server. Nothing leaves your infrastructure.

Contents

  1. Installation — requirements, one-click install, first setup
  2. Configuration — .env reference, SMTP, TLS, classification, white-labeling
  3. MCP setup — register the server in Claude Code and use it
  4. Editions & licensing — Developer / Team / Enterprise, entering your licence
  5. Troubleshooting — common issues and fixes

At a glance
Delivery Docker Compose (one install.sh)
Stores MongoDB (metadata) + sqlite-vec (vectors, runs on any CPU — no AVX2 needed)
Search Hybrid: vector cosine KNN + BM25/FTS, fused with Reciprocal Rank Fusion
Embeddings Local via Text-Embeddings-Inference (default multilingual-e5-small, ~1 GB RAM)
Admin UI Vue 3 + AdminLTE 4 (dark) — users, spaces, documents, tags, settings
MCP tools memory_search, memory_list, memory_get, memory_save
Auth Local accounts + optional LDAP/AD SSO (Enterprise)
Languages UI in English (default) + German, French, Spanish

Requirements

  • A 64-bit Linux server with Docker and Docker Compose v2
  • ~2 GB RAM free for the default light embedding model (more for bge-m3)
  • A domain name if you want public HTTPS (optional — works on LAN too)

Continue with Installation »

Installation

1. Requirements

  • A 64-bit Linux server (Ubuntu/Debian/Alma — anything with Docker works)
  • Docker and Docker Compose v2 (docker compose version)
  • openssl (for secret generation — preinstalled on most systems)
  • ~2 GB free RAM for the default embedding model

AI-Memory runs entirely in Docker. You never install PHP, Node, Python or a database on the host.

2. One-click install

Unzip the package, then run the installer:

unzip ai-memory.zip && cd ai-memory
./install.sh

The installer:

  1. checks Docker, Compose and openssl,
  2. creates .env and generates the MongoDB password, JWT secret and admin token,
  3. asks whether you run locally (http://localhost:8081) or on a public domain,
  4. builds the images and starts the stack,
  5. waits until the API is healthy and prints the URL.

For an unattended install with local defaults:

./install.sh --yes

3. First-time setup

Open the printed URL and go to /#/setup. Create the first administrator account — this becomes the super-admin. After that, /#/setup is locked.

http://localhost:8081/#/setup

Log in, and you'll land on the dashboard. From here you can upload documents, create spaces, invite users and configure the server (see Configuration).

4. Public HTTPS (optional)

If you chose public domain during install, AI-Memory's built-in Caddy will terminate TLS for you. After first login:

  1. Point a DNS A record for your domain at the server.
  2. Go to Settings → SSL / HTTPS, enter the domain and your DNS provider token (Cloudflare / Hetzner / DigitalOcean), enable it and save.
  3. A Let's Encrypt certificate is issued automatically (DNS-01). HTTPS survives restarts — the configuration is stored in the database.

No external tunnel or reverse proxy is required.

5. Manual install (advanced)

If you prefer to do it by hand:

cp .env.example .env
# generate the three required secrets:
sed -i "s/^MONGO_ROOT_PASSWORD=.*/MONGO_ROOT_PASSWORD=$(openssl rand -hex 24)/" .env
sed -i "s/^JWT_SECRET=.*/JWT_SECRET=$(openssl rand -hex 32)/" .env
sed -i "s/^MEMORY_ADMIN_TOKEN=.*/MEMORY_ADMIN_TOKEN=$(openssl rand -hex 32)/" .env

docker compose build
docker compose up -d

6. Updating

git pull        # or unzip the new release over the old folder
docker compose build
docker compose up -d

Your data lives in Docker volumes and is preserved across updates. Always keep a backup of .env and the mongo-data / mcp-data volumes.

Continue with Configuration »

Configuration

Most settings live in .env (set once, at install) — runtime settings like SMTP, TLS, classification and branding are managed from the Settings screen in the web UI and stored in the database.

.env reference

Key Meaning
SITE_ADDRESS :80 for local, or your domain for public HTTPS
APP_BASE_URL / MCP_PUBLIC_URL Public URLs used in invite links and client configs
MONGO_ROOT_PASSWORD MongoDB password (generated by install.sh)
JWT_SECRET Session/JWT signing secret (generated)
MEMORY_ADMIN_TOKEN Internal API ↔ MCP token (generated)
EDITION / LICENSE_KEY Edition fallback / licence key (prefer the UI)
EMBED_MODEL / EMBED_DIM Embedding model. Default multilingual-e5-small (384). For best quality use BAAI/bge-m3 (1024) — needs ~4 GB RAM and a re-ingest
BRAND_*, VENDOR_*, FEEDBACK_TO White-label branding (see below)

Never commit .env. Back it up — it holds your secrets.

Settings → E-mail / SMTP

Needed for the invite / multi-user flow. Enter host, port, credentials and the From address, toggle Active, and use Send test to verify. Changes take effect immediately (no restart).

Settings → SSL / HTTPS

Automatic HTTPS via the built-in Caddy and Let's Encrypt DNS-01:

  1. Enter your domain and ACME e-mail.
  2. Pick your DNS provider (Cloudflare / Hetzner / DigitalOcean) and paste an API token with DNS-edit rights.
  3. Toggle Active and save. The certificate is provisioned automatically and renews itself; the status badge turns green when ready.

DNS-01 works even when the server is not publicly reachable on port 80.

Settings → Classification (optional)

Optional AI tagging: when enabled, uploaded documents are automatically tagged and given a clean display name. Provide an Anthropic-compatible /v1/messages endpoint and API key, pick a model, toggle Active. Without it, documents keep their original filename and you tag them manually.

Settings → SSO / LDAP (Enterprise)

Map your Active Directory / LDAP groups to spaces and roles. Configure host, bind DN, base DN, the user filter and group→space mappings, then test with a real account. Available on the Enterprise edition only.

White-label branding

BRAND_NAME=AI-Memory
BRAND_TAGLINE=Self-hosted team memory for Claude & LLMs
BRAND_ACCENT=#5BC5F2
APP_VERSION=1.0.0
VENDOR_NAME=Invent-IT
VENDOR_URL=https://invent-it.eu
VENDOR_FOOTER=true          # set false (Extended License) to hide the footer
FEEDBACK_TO=support@invent-it.eu
MCP_SERVER_NAME=ai-memory
POLICY_ORG_NAME=            # optional org name in the policy header

The brand name, tagline and accent colour drive the whole UI. Replace web/backend/src/assets/logo.png with your own logo and rebuild.

Continue with MCP setup »

MCP setup — connect Claude Code

AI-Memory exposes your knowledge to AI assistants through an MCP server (Model Context Protocol, streamable HTTP). Once registered, your assistant can search and write memories with four tools.

1. Get your access token

Every user has a personal access token.

  1. Log in to the web UI.
  2. Open My Access (user menu).
  3. Copy the MCP URL and Bearer token.

The MCP URL is <your-base-url>/mcp (e.g. https://memory.example.com/mcp).

2. Register the server in Claude Code

claude mcp add --transport http ai-memory \
  https://memory.example.com/mcp \
  --header "Authorization: Bearer <YOUR_TOKEN>"

Verify it connected:

claude mcp list
# ai-memory: https://memory.example.com/mcp (HTTP) - ✓ Connected

After adding or changing the token, fully reload Claude Code so the tools are registered for the session.

3. The tools

Tool What it does
memory_search(query, limit?, type?) Hybrid search across the spaces and personal memory you can access. Returns the top snippets.
memory_list(type?) Index of everything you can access (one line per source).
memory_get(...) Full text of a specific entry.
memory_save(title, content, tags?) Save (or update) a note in your personal memory. Idempotent by title.

Ask your assistant to "search the team memory for X" and it will call memory_search first. New findings can be written with memory_save.

4. Spaces vs personal memory

  • Spaces are shared knowledge bases. Everyone in a space can search it.
  • Personal memory is private to a single user (available on Team and Enterprise editions).

memory_save always writes to the caller's personal memory. To make a note shared, move it into a space from the web UI (My Memories → Move to space).

5. Always-loaded knowledge (PreLoad / PreToolUse)

Documents in a space can be flagged so they are injected into every session, without the assistant having to search for them:

  • PreLoad — included in context at the start of every session.
  • PreToolUse — surfaced as rules to read before acting.

Set the flag per document in Documents (the LoadMode column). Use it for your coding conventions, hard rules and project orientation.

6. Uploading knowledge

Upload .md, .txt and similar text documents from the web UI (Documents → Upload, or My Memories for personal notes). Each document is chunked, embedded and indexed automatically. Optional AI classification can tag and name documents for you (see Configuration).

Continue with Editions & licensing »

Editions & licensing

AI-Memory is one codebase gated by a signed licence key. Without a licence it runs as the Developer edition.

Editions

Developer Team Enterprise
Spaces 1 1 unlimited
Users (incl. admin) 3 10 unlimited
Personal memories — ✓ ✓
SSO / LDAP — — ✓

Quotas are enforced server-side: when a limit is reached, the matching action (create space, invite user, enable personal memory, configure LDAP) is blocked with a clear message, and the corresponding button is disabled in the UI.

Entering your licence

  1. Go to Settings → License.
  2. Paste the licence key you received with your purchase.
  3. Click Activate. The edition, expiry and limits update immediately.

The key is verified locally using an embedded public key — no internet connection or phone-home is required at runtime. Precedence is: licence in the database → LICENSE_KEY environment variable → Developer fallback.

How licences are issued

Each purchase on CodeCanyon maps to an edition. After buying, you activate your purchase code once to receive a signed licence key, which you paste into Settings → License. The licence is perpetual (CodeCanyon regular licence) and tied to your purchase.

White-labeling (Extended License)

With the Extended License you can rebrand the product via .env:

BRAND_NAME=Your Brand
BRAND_TAGLINE=Your tagline
BRAND_ACCENT=#5BC5F2
VENDOR_FOOTER=false          # hide the "powered by" footer

Replace web/backend/src/assets/logo.png with your own logo. See Configuration for the full branding reference.

Continue with Troubleshooting »

Troubleshooting

The stack won't start / a container is unhealthy

docker compose ps          # see which service is down
docker compose logs -f api # follow a service's logs (api, mcp, web, mongodb, tei, caddy)

Most first-run issues are resources: the embedding service (tei) downloads the model on first boot — give it a few minutes and enough RAM.

"unable to open database file" (mcp)

The data volume lost its permissions. Recreate it:

docker compose down
docker volume rm ai-memory_mcp-data
docker compose up -d

(Your documents are re-indexed from MongoDB on next upload; back up first if unsure.)

MCP shows "not connected" in Claude Code

  • Check the URL is <base-url>/mcp and the Bearer token is correct.
  • After changing the token, fully reload Claude Code — a soft reconnect does not always re-register the tools.
  • Confirm the server is reachable: curl -s <base-url>/api/meta.

Search returns nothing / poor results

  • Make sure the document was uploaded into the space you are searching (a personal note is not visible in a space and vice-versa).
  • Very large models give better results: switch EMBED_MODEL=BAAI/bge-m3 + EMBED_DIM=1024 in .env, then re-index from Settings. This needs ~4 GB RAM.

SMTP test fails

  • Double-check host/port and that Active is toggled on.
  • For port 587 use SMTP_SECURE=false (STARTTLS); for port 465 use true.

HTTPS certificate not issued

  • The DNS API token must have DNS edit rights for the zone.
  • The domain's DNS record must exist. Check Settings → SSL status and docker compose logs -f caddy.

Edition limit reached unexpectedly

The server enforces quotas (spaces, users, personal memory, SSO) per edition. Check Settings → License — paste your key to unlock your edition. Without a key the product runs as Developer (1 space, 3 users).

Reset everything (danger)

docker compose down -v   # removes ALL volumes and data

Still stuck? Contact support at the address shown on the About page.