Audience: IBM Db2 Community — developers, DBAs, and architects evaluating Db2 12.1.5 vector search
Repo: github.com/ncz-os/mnemos → quickstart/ (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 DSN — MNEMOS_DATABASE_DSN / MNEMOS_PERSISTENCE_BACKEND. mnemos self-provisions schema (vector column + index) on first connect; no hand-written DDL.
-
Parity is enforced in CI — tests/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 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:
-
Agent calls search_memory with a natural-language query.
-
mnemos embeds the query via the bundled bge-m3 model (1024 dimensions, CPU GGUF).
-
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.
-
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 /mcp — mnemos 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: true → VECTOR_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:
-
Export memories via MIF (mnemos mif export) or replicate the database.
-
Point MNEMOS_DATABASE_DSN at Db2 Standard or Advanced.
-
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