Db2

Db2

Where DBAs and data experts come together to stop operating and start innovating. Connect, share, and shape the AI era with us.


#Data


#Data
#Databases
#Operatingsystems
#Db2
#Databasesolutions
 View Only

Persistent AI Agent Memory on Db2 12.1.5 VECTOR — mnemos Quick Start

By Jason Perlow posted 9 days ago

  

Audience: IBM Db2 Community — developers, DBAs, and architects evaluating Db2 12.1.5 vector search
Repo: github.com/ncz-os/mnemosquickstart/ (also on GitLab and Codeberg)

The problem: your AI assistant forgets everything

If you use Claude Code, Cursor, OpenAI Codex, or ChatGPT for real engineering work, you have felt this: every new session starts cold. The model does not remember that you fixed the Db2 bind-order bug last Tuesday, which registry variables your instance needs, or that your team standardized on EUCLIDEAN distance for normalized embeddings.

Cloud-hosted “memory” features help, but they store context on someone else’s infrastructure, outside your audit boundary, and outside the database your organization already runs.

mnemos is an open-source agent-memory server that solves this differently: memories live in your database, embedded as vectors, recalled by semantic similarity, and exposed to agents over MCP (Model Context Protocol). Its EPIMONE persistence layer uses an ABC (Abstract Base Class) backend contract, so the same memory model runs on Db2, Oracle, PostgreSQL, MySQL, MariaDB, or SQLite — you pick the engine, mnemos supplies the schema and vector recall path.

This Quick Start leads with Db2 Community Edition for Db2’s long-track stability, enterprise performance, and native 12.1.5 VECTOR stack — but the same image and agent integrations run unchanged on every backend. Two Docker Compose commands start up Db2 CE, a CPU-embedded server, and mnemos. No GPU, no proprietary vector SaaS, no cloud account.

This post covers EPIMONE’s multi-database design, why Db2 is the right choice here, the Db2 features it leverages, and how to wire Claude, Cursor, Codex, and ChatGPT to the same Db2-backed memory store.

EPIMONE: one memory model, every enterprise database

mnemos does not hard-code agent memory to a single vector database or a proprietary SaaS store. Persistence lives in EPIMONE — mnemos’s backend-neutral storage layer (mnemos/persistence/) built on Python’s abc.ABC repository contract. Every API route, MCP tool, and agent integration talks to abstract repositories (MemoryRepository, KGRepository, VersionRepository, federation, compression, audit, …); each supported database supplies a swappable backend that implements the same contract.

What that means in practice:

  • One mnemos image, one REST/MCP surface, one MIF portability format — regardless of which database sits underneath.

  • Switch backends by changing a DSNMNEMOS_DATABASE_DSN / MNEMOS_PERSISTENCE_BACKEND. mnemos self-provisions schema (vector column + index) on first connect; no hand-written DDL.

  • Parity is enforced in CItests/test_persistence_parity.py runs the same memory, search, federation, and compression scenarios against every backend so behavior does not drift.

Supported persistence backends (six engines)

Backend

Typical deployment

Native vector search

IBM Db2 12.1.5+

Enterprise OLTP, warehouse, CE eval

VECTOR + VECTOR_DISTANCE + DiskANN index

Oracle Database 23ai / 26ai

Enterprise, Exadata, 23ai Free eval

AI Vector Search (HNSW / INMEMORY NEIGHBOR GRAPH)

PostgreSQL + pgvector

Cloud-managed Postgres, homelab, SaaS

pgvector HNSW

MySQL 9.0 Enterprise / HeatWave

Managed cloud MySQL (RDS, Aurora, HeatWave)

VECTOR + VECTOR_DISTANCE

MariaDB 11.7+

Pure open-source MySQL-family

Native VECTOR + HNSW index

SQLite + sqlite-vec

Edge, laptop, offline-first

sqlite-vec (dev / single-user)

The Quick Start Docker profiles exercise four free editions of the enterprise-class engines (Db2 CE, Oracle 23ai Free, Postgres, MariaDB). Production deployments point the same mnemos binary at licensed Db2 Standard/Advanced, Oracle EE, Amazon RDS/Aurora, Azure Database for PostgreSQL, HeatWave, or any supported DSN — the agent integrations and REST API do not change.

Memories export and import through MIF (Memory Interchange Format), so you can migrate between backends — including from a Postgres dev stack to a Db2 production cluster — without rewriting agent configs.

Why Db2 leads this Quick Start

We lead the IBM Db2 Community write-up with Db2 not because mnemos is Db2-only — it is explicitly multi-backend by design — but because Db2 is a strong fit for the enterprise agent-memory workload and because Db2 12.1.5 finally ships the native vector primitives that workload needs.

Why Db2 for enterprise agent memory

Factor

Why it matters for mnemos

Long-track stability

Db2 has decades of production hardening in mission-critical OLTP, warehousing, and analytics. Agent memory is audit-grade data — versioned, retained, governed — not ephemeral cache. Teams trust Db2 to stay up and stay consistent.

Performance at scale

DiskANN vector indexing on 12.1.5, FETCH APPROX FIRST for indexed ANN recall, and a mature buffer-pool / I/O stack give predictable latency as memory corpora grow into millions of embedded rows.

Enterprise penetration

Db2 runs in a large share of Fortune-class environments — often alongside existing security, backup, HA, and compliance tooling. Storing agent context in the database the organization already operates beats introducing a parallel vector silo.

Generous free eval

Db2 Community Edition (permanent license, 4 cores, 8 GB RAM, unlimited database size) lets anyone reproduce the full vector stack — datatype, distance function, index, agent integrations — at zero cost.

Native 12.1.5 vector stack

VECTOR(n, FLOAT32), VECTOR_DISTANCE, and CREATE VECTOR INDEX ... WITH DISTANCE EUCLIDEAN are first-class Db2 features — exactly what EPIMONE’s Db2BackendNative adapter targets.

Db2 12.1.5 VECTOR mapped to agent-memory requirements

Requirement

What agent memory looks like

Db2 12.1.5 answer

Durable storage

Text + metadata + 1024-float embedding per memory, versioned, auditable

Native VECTOR(n, FLOAT32) column on CLOB content

Semantic recall

“Where did we document the bind syntax?” with no shared keywords

VECTOR_DISTANCE(..., EUCLIDEAN) over indexed embeddings

Low latency at scale

Agents query memory on every non-trivial turn

DiskANN vector index via CREATE VECTOR INDEX ... WITH DISTANCE EUCLIDEAN

Enterprise path

Dev on CE, production on licensed Db2

Same SQL, same schema — switch MNEMOS_DATABASE_DSN to Standard/Advanced

Operational familiarity

Teams already run Db2 for OLTP/warehouse

One engine for transactional data and agent context

Roadmap: IBM POWER and IBM Z (Linux)

mnemos today is validated on Db2 LUW (Linux x86_64 and arm64 containers). Our stated intention, given engineering resources and hardware access, is to port and qualify mnemos on IBM POWER (Linux and AIX) and IBM Z (Linux on Z / s390x) — the platforms where many Db2 enterprise deployments actually run. That covers runtime builds and CI on ppc64le, AIX, and s390x; Db2 backend qualification on Db2 for Linux on POWER/Z (LUW-derived, same native SQL path EPIMONE already emits); vector index and VECTOR_DISTANCE performance validation; and non-x86 Quick Start profiles.

Because of EPIMONE’s ABC design, this is platform qualification and tuning, not a rewrite. (Db2 for z/OS is a separate release train with its own dialect and vector GA timeline; Linux on Z is the near-term target.) IBMers or partners who can help with POWER/Z hardware, test instances, or distribution — please reach out via the repo or the Db2 Community thread.

Architecture: from agent tool call to Db2 vector search

mnemos systems architecture

 

mnemos agent-memory architecture on Db2 12.1.5 VECTOR

Figure: AI agents call mnemos over MCP; mnemos embeds content via bge-m3 and persists or queries native Db2 VECTOR columns through VECTOR_DISTANCE and the DiskANN index.

Flow:

  1. Agent calls search_memory with a natural-language query.

  2. mnemos embeds the query via the bundled bge-m3 model (1024 dimensions, CPU GGUF).

  3. mnemos runs native Db2 SQL: VECTOR_DISTANCE against the memories.embedding column, ordered ascending, with FETCH APPROX FIRST n ROWS ONLY to engage the DiskANN index.

  4. Results return to the agent with relevance scores; the agent uses them as session context.

Store is the mirror path: content → embed → INSERT/MERGE with an inlined VECTOR(...) literal.

What this integration actually exercises in Db2 12.1.5

This is not a lowest-common-denominator port with a generic vector shim. mnemos ships a first-class native Db2 adapter (Db2BackendNative) that emits Db2 SQL throughout:

Native VECTOR datatype

On first connect, mnemos self-provisions schema including:

CREATE TABLE memories (
    id VARCHAR(100) NOT NULL PRIMARY KEY,
    content CLOB,
    category VARCHAR(100),
    -- ... metadata, provenance, audit columns ...
    embedding VECTOR(1024, FLOAT32)
);

The dimension comes from MNEMOS_EMBEDDING_DIM (1024 for the bundled bge-m3 embedder). The Quick Start sets this correctly; mismatches produce cast errors — see Configuration pitfalls below.

VECTOR_DISTANCE with EUCLIDEAN metric

The production semantic-search query path (simplified):

SELECT m.id, m.content, m.category,
      VECTOR_DISTANCE(
          m.embedding,
          VECTOR(?, 1024, FLOAT32),
          EUCLIDEAN
      ) AS rank_score
FROM memories m
WHERE m.deleted_at IS NULL
  AND m.embedding IS NOT NULL
ORDER BY VECTOR_DISTANCE(
          m.embedding,
          VECTOR(?, 1024, FLOAT32),
          EUCLIDEAN
      ) ASC
FETCH APPROX FIRST ? ROWS ONLY;

Why EUCLIDEAN, not COSINE? Db2 12.1.5’s DiskANN vector index supports EUCLIDEAN distance. mnemos L2-normalizes embeddings at ingest time; for unit-norm vectors, EUCLIDEAN and COSINE distance produce the same top-K ordering (|a−b|² = 2 − 2·cos(a,b)). Semantic recall semantics are preserved while the index is engaged.

Set MNEMOS_DB2_VECTOR_INDEX=exact to force a sequential scan for parity debugging; default approx engages DiskANN.

DiskANN vector index

After enabling vector indexing at the instance level, mnemos creates:

CREATE VECTOR INDEX idx_memories_emb_diskann
    ON memories(embedding) WITH DISTANCE EUCLIDEAN
    PCT_COMP_VECT_SIZE 15
    BUILD_PARALLELISM 4
    BUILD_MEM_BUDGET 2;

Tuning knobs (PCT_COMP_VECT_SIZE, BUILD_PARALLELISM, BUILD_MEM_BUDGET) are substituted at migration time — validated on ~12k × 768-dim rows with measurable query-time improvement vs defaults.

Other Db2-native SQL in the hot path

Pattern

Db2 form

Why it matters

Upsert

MERGE ... USING SYSIBM.SYSDUMMY1

Idempotent memory writes

Keys

GENERATE_UNIQUE()

Db2-native unique IDs

Binds

? positional (via ibm_db)

No Oracle :name leakage

JSON validation

SYSTOOLS.JSON2BSON

Metadata integrity

Timestamps

CURRENT TIMESTAMP

Native temporal types

The only registry variable related to “compatibility” in the Quick Start is DB2_COMPATIBILITY_VECTOR=ORA — Db2’s server-side feature toggle that enables the 12.1.5 VECTOR datatype and VECTOR_DISTANCE. It is not an application-side Oracle translation layer.

Instance registry variables

The one-time init script applies:

db2set DB2_COMPATIBILITY_VECTOR=ORA    # enable VECTOR datatype + VECTOR_DISTANCE
db2set DB2_VECTOR_INDEXING=YES         # enable CREATE VECTOR INDEX
db2stop && db2start                    # registry changes require restart

The Quick Start docker-compose.yml also sets these on the Db2 container; the script guarantees they took effect even if the database was created before the vars were active.

Install: Db2 lane in under ten minutes

Prerequisites: Docker + Docker Compose, ~6 GB free RAM (Db2 first boot is the heavy step), no GPU.

git clone https://github.com/ncz-os/mnemos
cd mnemos/quickstart
cp .env.example .env                 # set DB_PASSWORD (required — no default in repo)
docker compose --profile db2 up -d
./scripts/init-db2-vectors.sh        # one-time: VECTOR datatype + vector indexing
curl -s localhost:5002/health        # {"status":"healthy", ...}

On first boot, the embed service downloads the bge-m3 GGUF model (~600 MB). The first store may take 1–2 minutes while the embedder loads; subsequent operations are fast.

Prove semantic recall (REST)

Store a memory:

curl -s localhost:5002/v1/memories -H 'content-type: application/json' \
  -d '{"content":"Db2 12.1.5 stores agent memory in a native VECTOR column","category":"reference"}'

Search by meaning — note "semantic": true (not mode: "semantic"):

curl -s localhost:5002/v1/memories/search -H 'content-type: application/json' \
  -d '{"query":"where does mnemos keep memory","limit":3,"semantic":true}'

You get the memory back with a relevance score even though the query shares almost no keywords with the stored text.

The quokka demo (pure vector similarity)

Store:

curl -s localhost:5002/v1/memories -H 'content-type: application/json' \
  -d '{"content":"The quokka is a small marsupial known as the happiest animal on Earth","category":"reference"}'

Search:

curl -s localhost:5002/v1/memories/search -H 'content-type: application/json' \
  -d '{"query":"which marsupial demonstrates vector search","limit":3,"semantic":true}'

Db2 returns the quokka note — no shared tokens, pure embedding similarity through VECTOR_DISTANCE and the DiskANN index.

mnemos agent integrations — one Db2 store, every agent

mnemos ships first-class integration bundles so you do not hand-roll MCP wiring for each tool. Every agent below talks to the same Db2-backed memory — a note stored from Claude Code is semantically searchable from Cursor, Codex, and ChatGPT on the next query, because all paths hit the same memories.embedding column and DiskANN index.

Where the integration artifacts live

Path

What it is

integrations/

Drop-in bundles per agent framework — MCP config, skills, hooks, install scripts

docs/connectors/

Per-surface connector guides (Claude Code, Claude Desktop, Cursor, Codex, ChatGPT, …)

quickstart/docs/AGENTS.md

Minimal MCP snippets tuned for the Db2 Quick Start Docker stack

Start with integrations/README.md for the deployment model, then the bundle for your agent.

Three layers: access, awareness, enforcement

mnemos integrations deliberately separate three concerns:

Layer

What it does

Example

Access (MCP)

Agent can call memory tools

search_memories, create_memory over stdio or HTTP/SSE

Awareness (skills / AGENTS.md)

Agent knows when to use memory

Skill files, standing instructions in project rules

Enforcement (hooks)

Memory is injected before the model speaks

Claude Code SessionStart + UserPromptSubmit hooks

MCP alone gives an agent the ability to query Db2; hooks and skills turn that into reliable behavior. Claude Code is the only bundle with a built-in enforcement layer today — session hooks that pre-fetch from Db2 so context arrives before inference.

Two MCP transports

Quick Start (Db2 Docker lane) — lightweight bridge inside the compose stack:

MNEMOS_API_URL=http://localhost:5002 mnemos-mcp-server --stdio
# or: docker exec -i mnemos mnemos-mcp-server --stdio

Exposes simplified tools: save_memory and search_memory (semantic recall maps to "semantic": true on the REST API → Db2 VECTOR_DISTANCE).

Full mnemos install — canonical MCP server with the complete tool registry:

MNEMOS_BASE=http://localhost:5002 mnemos serve mcp-stdio

Exposes search_memories, create_memory, get_memory, knowledge-graph tools, version DAG tools, and more — all backed by the same Db2 schema. HTTP/SSE variant for remote agents:

mnemos serve mcp-http --host 0.0.0.0 --port 5004

The Quick Start runs with MNEMOS_AUTH_ENABLED=false for local eval. Enable auth + bearer tokens before any shared or production deployment.

Canonical MCP tools (full server)

Every connector in docs/connectors/ shares one tool registry. Key memory tools agents use against Db2:

Tool

Purpose

search_memories

Full-text + vector search (Db2 VECTOR_DISTANCE)

create_memory

INSERT new row + embed → VECTOR(1024, FLOAT32)

get_memory

Fetch by ID

update_memory / delete_memory

Mutate with version DAG audit trail

bulk_create_memories

Batch load (Docling ingest path)

kg_search / kg_create_triple

Knowledge graph over the same Db2 instance

Cursor may display tools with a UI prefix (mnemos_search_memories); approval rules match the canonical names above.

Automated smoke tests in tests/test_connector_smoke.py verify stdio registration for Claude Code, Claude Desktop, Cursor, Codex, Continue, Cline, and the HTTP/SSE bridge used by ChatGPT.

Claude Code — integrations/claude-code/ (strongest integration)

Claude Code was the original deployment target. mnemos ships a complete bundle: MCP config, three session hooks, and an idempotent installer.

Integration repo path: integrations/claude-code/
Connector guide: docs/connectors/claude-code.md

1. MCP server (tool access)

Per-project — copy the example config:

cp integrations/claude-code/mcp.example.json ./.mcp.json
# edit MNEMOS_BASE → http://localhost:5002 (Quick Start) or your Db2-backed mnemos host

{
  "mcpServers": {
    "mnemos": {
      "command": "/path/to/mnemos/venv/bin/mnemos",
      "args": ["serve", "mcp-stdio"],
      "env": {
        "MNEMOS_BASE": "http://localhost:5002"
      }
    }
  }
}

Quick Start alternative (bridge inside Docker — no local mnemos CLI):

{
  "mcpServers": {
    "mnemos": {
      "command": "docker",
      "args": ["exec", "-i", "mnemos", "mnemos-mcp-server", "--stdio"],
      "env": { "MNEMOS_API_URL": "http://localhost:5002" }
    }
  }
}

Verify with /mcpmnemos should list memory tools.

2. Session hooks (enforcement — pre-inference Db2 recall)

This is what makes Claude Code + Db2 feel like persistent memory rather than optional tooling. Three hook scripts ship in integrations/claude-code/hooks/:

Hook

Event

Db2 interaction

mnemos-session-start.sh

SessionStart

Fetches recent memories from /v1/memories, injects compact context block

mnemos-user-prompt-submit.sh

UserPromptSubmit

Semantic search on your prompt (semantic: trueVECTOR_DISTANCE), injects top matches

mnemos-stop.sh

Stop

Posts session transcript to /ingest/session for durable audit

Install (idempotent):

cd integrations/claude-code
./install.sh

Configure ~/.claude/mnemos-hooks.config:

export MNEMOS_BASE="http://localhost:5002"
# export MNEMOS_API_KEY=""   # when auth enabled
export MNEMOS_CONTEXT_LIMIT=5      # memories on session start
export MNEMOS_SEARCH_LIMIT=3       # semantic hits per prompt

Source from shell init so Claude Code inherits it:

echo '[ -f "$HOME/.claude/mnemos-hooks.config" ] && source "$HOME/.claude/mnemos-hooks.config"' >> ~/.zshrc

Hooks noop silently when MNEMOS_BASE is unset or Db2/mnemos is unreachable — safe to install before the Quick Start is running. Activity logs to /tmp/mnemos-hooks.log.

Dry-run:

MNEMOS_BASE=http://localhost:5002 ~/.claude/mnemos-hooks/mnemos-session-start.sh <<< '{}'

Claude Desktop — docs/connectors/claude-desktop.md

Claude Desktop spawns the stdio MCP server locally — same Db2 store as Claude Code, no tunnel required.

OS

Config path

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

Linux

~/.config/Claude/claude_desktop_config.json

Quick Start (auth disabled):

{
  "mcpServers": {
    "mnemos": {
      "command": "docker",
      "args": ["exec", "-i", "mnemos", "mnemos-mcp-server", "--stdio"],
      "env": {}
    }
  }
}

Production (full server + auth):

{
  "mcpServers": {
    "mnemos": {
      "command": "mnemos",
      "args": ["serve", "mcp-stdio"],
      "env": {
        "MNEMOS_BASE": "http://localhost:5002",
        "MNEMOS_API_KEY": "<your-bearer-token>"
      }
    }
  }
}

Restart Claude Desktop completely after editing. Verify: curl -fsS http://localhost:5002/health.

For HTTP/SSE (same mnemos backing multiple machines), see the remote MCP entry in docs/connectors/claude-desktop.md.

Cursor — docs/connectors/cursor.md + quickstart/docs/AGENTS.md

Cursor reads MCP servers from ~/.cursor/mcp.json (global) or .cursor/mcp.json (project). Settings → MCP shows registered tools after restart.

Full server:

{
  "mcpServers": {
    "mnemos": {
      "command": "mnemos",
      "args": ["serve", "mcp-stdio"],
      "env": {
        "MNEMOS_BASE": "http://localhost:5002",
        "MNEMOS_API_KEY": "<token-if-auth-enabled>"
      }
    }
  }
}

Quick Start (Docker bridge):

{
  "mcpServers": {
    "mnemos": {
      "command": "mnemos-mcp-server",
      "args": ["--stdio"],
      "env": { "MNEMOS_API_URL": "http://localhost:5002" }
    }
  }
}

Standing instruction: add to Cursor rules or project AGENTS.md:

Before non-trivial work, search mnemos for prior context. After solving something non-obvious, save a memory (reference, project, infrastructure) so the next session inherits it.

Cursor tool approval lists use exact registry names (search_memories, not the UI prefix mnemos_search_memories).

Windows + WSL: prefer HTTP/SSE (mnemos serve mcp-http on :5003 or :5004) over cross-boundary stdio — see docs/connectors/cursor.md.

OpenAI Codex — docs/connectors/codex-cli.md

Codex CLI 0.125.0+ registers MCP servers via CLI or ~/.codex/config.toml — same Db2-backed tools as Cursor and Claude. Full guide: docs/connectors/codex-cli.md.

Recommended CLI registration:

export MNEMOS_TOKEN="<your-bearer-token-or-empty-for-quickstart>"
codex mcp add mnemos \
  --env MNEMOS_BASE=http://localhost:5002 \
  --env MNEMOS_API_KEY="$MNEMOS_TOKEN" \
  -- mnemos serve mcp-stdio

Equivalent TOML:

[mcp_servers.mnemos]
command = "mnemos"
args = ["serve", "mcp-stdio"]

[mcp_servers.mnemos.env]
MNEMOS_BASE = "http://localhost:5002"
MNEMOS_API_KEY = "<token-if-auth-enabled>"

Quick Start bridge:

[mcp_servers.mnemos]
command = "mnemos-mcp-server"
args = ["--stdio"]
env = { MNEMOS_API_URL = "http://localhost:5002" }

Verify: codex mcp list | grep -i mnemos. Restart Codex after TOML edits.

ChatGPT — docs/connectors/chatgpt-pro-developer-mode.md

ChatGPT cannot spawn local processes — it connects over HTTPS + SSE to mnemos serve mcp-http. Every tool call still lands on the Db2 REST API (embed → VECTOR_DISTANCE → DiskANN).

Integration repo path: docs/connectors/chatgpt-pro-developer-mode.md
Alternate path (Plus tier, no Developer Mode): docs/connectors/openai-custom-gpt.md — OpenAPI Actions over REST

Developer Mode (Pro / Team / Enterprise / Edu)

1. Add MCP HTTP service to Quick Start:

# docker-compose.override.yml
services:
  mnemos-mcp-http:
    image: ghcr.io/ncz-os/mnemos-enterprise:sha-3d892a5
    depends_on: [mnemos-db2]
    restart: unless-stopped
    command: ["mnemos", "serve", "mcp-http", "--host", "0.0.0.0", "--port", "5004"]
    ports: ["5004:5004"]
    environment:
      MNEMOS_MCP_TOKENS: "chatgpt:${MNEMOS_MCP_TOKEN}:<mnemos-api-key>"
      MNEMOS_BASE: "http://mnemos:5002"
      MNEMOS_API_KEY: "<mnemos-api-key>"

export MNEMOS_MCP_TOKEN="$(openssl rand -hex 32)"
docker compose --profile db2 up -d mnemos-mcp-http
curl http://localhost:5004/healthz    # → ok

2. TLS tunnel (ChatGPT requires public HTTPS):

ngrok http http://localhost:5004
# or: cloudflared tunnel / Tailscale Funnel — see connector doc

3. Register connector: ChatGPT → Settings → Developer Mode → Connectors → Add custom

Field

Value

Name

MNEMOS

Connector URL

https://<your-tunnel>/sse

Authentication

Bearer Token

Token

$MNEMOS_MCP_TOKEN

ChatGPT completes the SSE handshake and exposes the full MCP tool registry. Ask: “Search my memory for Db2 vector index syntax” — ChatGPT calls search_memories, mnemos runs VECTOR_DISTANCE against Db2, results fold into the conversation.

4. Custom GPT Actions (Plus and above, no Developer Mode):

mnemos dump-openapi --target gpt-actions > mnemos-openapi.json

Upload the spec in GPT Builder with Bearer auth pointing at your mnemos REST endpoint. Sync REST path (no streaming MCP), same Db2 backend.

Integration summary

Agent

Integration bundle

Transport

Db2 recall path

Claude Code

integrations/claude-code/ + hooks

stdio MCP + pre-inference hooks

Hooks call REST semantic search; MCP tools for explicit R/W

Claude Desktop

docs/connectors/claude-desktop.md

stdio MCP (or HTTP/SSE)

Agent-initiated search_memories → Db2

Cursor

docs/connectors/cursor.md

stdio MCP (or HTTP/SSE)

Agent-initiated tool calls → Db2

OpenAI Codex

docs/connectors/codex-cli.md

stdio MCP (0.125.0+)

Same registry as Cursor

ChatGPT Pro

docs/connectors/chatgpt-pro-developer-mode.md

HTTP/SSE MCP

Remote connector → same Db2 store

ChatGPT Plus

docs/connectors/openai-custom-gpt.md

REST Actions

Direct /v1/memories/search with semantic: true

Bonus frameworks in integrations/: OpenClaw (integrations/openclaw/), ZeroClaw (integrations/zeroclaw/), and Hermes (integrations/hermes/) — each ships an MCP example, skill file, and AGENTS.md snippet. All connect to the same Db2-backed mnemos host.

Standing instruction (all agents without hooks)

For Cursor, Codex, Claude Desktop, and ChatGPT, add a persistent rule:

Before starting non-trivial work, search mnemos for prior context on this topic. After solving something non-obvious, create a memory (category project, reference, infrastructure, or decisions) so the next session — on any connected agent — inherits it from Db2.

That turns Db2 Community Edition into durable, multi-agent, cross-session memory.

Document-heavy workflows: Docling → Db2

For teams ingesting manuals, runbooks, or design PDFs, the Quick Start includes docling_ingest.py — built on Docling (Linux Foundation; previously IBM Docling). It converts PDF/DOCX/PPTX to clean Markdown, chunks by heading, and bulk-loads into Db2-backed memory (or exports a portable MIF bundle):

pip install docling requests
python quickstart/mif-tools/docling_ingest.py ./docs/runbook.pdf \
  --mnemos-url http://localhost:5002 \
  --category reference \
  --source-tag db2-runbook

Each chunk is embedded and stored in the same VECTOR(1024, FLOAT32) column — your agent can semantically recall “what does the runbook say about registry variables?” without re-uploading the PDF every session.

Embeddings Configuration 

Setting

Value (Quick Start)

Embedder

bge-m3 (quantized Q8 GGUF)

MNEMOS_EMBEDDING_DIM

1024

Semantic floor tuning for quantized bge-m3

The Quick Start sets:

MNEMOS_SEMANTIC_FLOOR: "0.45"
MNEMOS_SEMANTIC_MARGIN_FLOOR: "0"

Quantized bge-m3 compresses similarity scores (~0.55–0.58 for good paraphrases vs 0.70+ for full-precision models). The default floor of 0.65 can silently drop valid hits. Re-tune whenever you change embedders.

Production hardening

Before exposing mnemos beyond localhost:

  • Set MNEMOS_AUTH_ENABLED=true and configure bearer tokens.

  • Use per-client tokens (MNEMOS_MCP_TOKENS) for HTTP/SSE connectors.

  • Point MNEMOS_DATABASE_DSN at your managed Db2 instance (UTF-8, 32K pagesize).

From Community Edition to production — any backend

Nothing in the Quick Start is CE-specific except the Db2 license envelope. EPIMONE’s ABC design means the same upgrade pattern applies to every engine:

Eval / dev

Production

Db2 Community Edition

Db2 Standard / Advanced (LUW; POWER/Z Linux when qualified)

Oracle 23ai Free

Oracle Database Enterprise / 26ai

PostgreSQL + pgvector (Docker)

Managed Postgres (RDS, Azure, Cloud SQL, self-hosted cluster)

MariaDB (Docker)

Managed MariaDB or MySQL-compatible cloud

When you outgrow Db2 CE’s 4 cores / 8 GB:

  1. Export memories via MIF (mnemos mif export) or replicate the database.

  2. Point MNEMOS_DATABASE_DSN at Db2 Standard or Advanced.

  3. Re-run init registry vars (DB2_COMPATIBILITY_VECTOR, DB2_VECTOR_INDEXING) on the target instance.

Same schema, same VECTOR_DISTANCE queries, same DiskANN index syntax — mnemos does not care which Db2 edition backs it. Agent integrations (integrations/, docs/connectors/) require no changes when you swap DSNs; only the persistence layer underneath changes.

Documentation note for Db2 vector early adopters

While building this integration, we verified index syntax on Db2 12.1.5:

Working:

CREATE VECTOR INDEX ix_name ON tbl(vec_col) WITH DISTANCE EUCLIDEAN;

…after db2set DB2_VECTOR_INDEXING=YES and instance restart.

Returns SQL0104N on 12.1.5:

CREATE INDEX ... USING HNSW ...
CREATE INDEX ... USING DISKANN ...

If any published examples still show the CREATE INDEX ... USING <algo> form, aligning them with the CREATE VECTOR INDEX ... WITH DISTANCE EUCLIDEAN syntax would help early adopters — flagging here in case it is useful for the doc team.

Similarly, query-time tuning knobs like SEARCH_LIST_SIZE / SEARCH_BEAM_WIDTH returned SQL0104N on the 12.1.5 build we tested; they may arrive in a later fix pack.

Who this is for

  • Db2 practitioners and IBMers: A reproducible, end-to-end demo of Db2 12.1.5’s VECTOR type, VECTOR_DISTANCE, DiskANN indexing, and FETCH APPROX FIRST — driving a real workload, not a synthetic benchmark. The SQL in mnemos/persistence/db2.py and migrations_db2/ is what Db2 runs in production. If you can help qualify mnemos on POWER (Linux/AIX) or Z (Linux), get in touch.

  • Enterprise platform teams: EPIMONE drops mnemos into the database you already run — no parallel vector store, same MCP tools and integrations on any backend.

  • AI/agent developers: Private, durable, cross-session memory for coding assistants, on enterprise-grade storage rather than a vendor memory service.

  • Document and knowledge teams: Docling ingestion + Db2 vector recall turns static PDFs into agent-queryable institutional memory.

Links and next steps

Resource

URL

Repository

github.com/ncz-os/mnemos

Quick Start (Db2 lane)

quickstart/

Agent integration bundles

integrations/ (Claude Code hooks, OpenClaw, ZeroClaw, Hermes)

Connector guides

docs/connectors/ (Claude Desktop, Cursor, Codex, ChatGPT, …)

Quick Start agent snippets

quickstart/docs/AGENTS.md

Claude Code integration

integrations/claude-code/README.md

ChatGPT Developer Mode

docs/connectors/chatgpt-pro-developer-mode.md

EPIMONE persistence layer

mnemos/persistence/ (ABC backends)

Backend comparison

quickstart/docs/BACKENDS.md

Db2 VECTOR docs

IBM Db2 12.1.x — Vector values

VECTOR_DISTANCE

IBM Db2 12.1.x — VECTOR_DISTANCE

Fully open source (Apache 2.0). Db2 Community Edition and the alternative backends in the Quick Start (PostgreSQL/pgvector, Oracle 23ai Free, MariaDB 11.7+) are all free to evaluate.

Questions, feedback, and war stories welcome in the comments — especially from anyone running vector indexes on Db2 12.1.5 in the wild. If you try the Quick Start, I’d love to hear how FETCH APPROX FIRST behaves at your corpus size.

Jason Perlow

About the author

Jason Perlow is an open-source developer and the creator of mnemos, zoder (a free Codex clone that works with open-source models), and tokenomics (an LLM spend-tracking engine for AI agents). An IBM Global Technology Services alumnus, he has been involved in open source since 1995 — as the founding Sr. Technology Editor of Linux Magazine, Editorial Director of the Linux Foundation, and a ZDNET columnist for 18 years. You can find more of his writing on his personal blog at https://www.techbroiler.net

1 comment
22 views

Permalink

Comments

Hi Jason, thanks for this article, very interesting use of Db2's vector search capabilities. Let me know if you have questions about using vector indexes, I think you seem to have had some trouble with them, and we can help! Christian