Mnemosyne MCP Server: Known Issues and Technical Debt

Level 3 (Detail) — Known issues and code-level gaps for the semantic memory service.

Scope

This page documents known technical debts, risks, and undocumented behavior found in the mnemosyne-mcp-server codebase at commit baseline 2026-04. Each item links to the canonical TD register in AGENTS.ctx/memory/debts.md and to the relevant source code paths.

Active Debts

TD-002: Embedding Dimension Mismatch (High)

  • Area: mnemosyne-mcp-server — internal/db/db.go, internal/embedding/embedding.go
  • Problem: The DB layer defaults to 3072 vector dimensions when the memories table is empty (fallback in autoDetectDimensions). The embedding layer hardcodes gemini-embedding-001, which produces 768-dimensional vectors. A fresh DB with no rows will be created with vector(3072), causing pgvector errors on every insert because 768-dim vectors cannot be stored in a 3072-dim column.
  • Trigger: First deployment on an empty database.
  • Workaround: If at least one memory already exists with the correct dimension, autodiscovery (vector_dims()) works correctly and no mismatch occurs.
  • Code paths:
    • internal/db/db.go — dimension fallback constant and autoDetectDimensions()
    • internal/embedding/embedding.go — hardcoded DefaultModel = "gemini-embedding-001"
  • Context reference: AGENTS.ctx/mnemosyne-mcp-server/CONTEXT.md

No Embedding Model Override

  • Area: mnemosyne-mcp-server — internal/embedding/embedding.go
  • Problem: The embedding model is a Go const (DefaultModel = "gemini-embedding-001") with no environment variable to override it. Changing the model requires source code modification.
  • Related: TD-002 — any model change would also need dimension alignment.

Async Ingestion Silently Swallows Errors

  • Area: mnemosyne-mcp-server — internal/logic/logic.go
  • Problem: ingest_memory returns {"status": "queued", "request_id": "..."} immediately. The actual embedding+DB insert runs in a background goroutine. If the embedding API call fails or the DB insert fails, the error is logged but never reported back to the caller. There is no status-polling or callback mechanism.
  • Impact: Callers (agents, tools) believe ingestion succeeded when it may have failed.
  • Code path: internal/logic/logic.go — IngestMemoryAsync() and the worker loop

Temporal Search Filters Unreachable from MCP

  • Area: mnemosyne-mcp-server — internal/logic/logic.go, internal/mcp/mcp.go
  • Problem: The Controller.SearchMemories method accepts daysBack, startStr, endStr parameters for temporal filtering, and the DB layer supports timestamp >= $3 AND timestamp <= $4 filters. However, the MCP tool retrieve_memories only exposes query and limit — the temporal parameters are always passed as 0, "", "".
  • Impact: Temporal search is implemented but unusable from any MCP client.
  • Code paths: internal/mcp/mcp.go:handleRetrieve() — call site; internal/logic/logic.go:SearchMemories() — unused params

In-Memory Dedup Cache Unbounded

  • Area: mnemosyne-mcp-server — internal/logic/logic.go
  • Problem: The cache map in Controller stores content_hash -> timestamp entries with a 10-minute TTL, but entries are never explicitly evicted after expiry. The map grows without bound proportional to unique ingestion volume.
  • Impact: Memory leak under sustained ingestion load. Low risk at current TazLab scale.

No Graceful Shutdown

  • Area: mnemosyne-mcp-server — cmd/mnemosyne-mcp/main.go
  • Problem: The server does not handle SIGTERM/SIGINT. database.Close() runs via defer on main() exit, but the background ingestion worker goroutine is not cleanly drained. In-flight embeddings may be lost during shutdown.

HTTP Mode Has No Authentication

  • Area: mnemosyne-mcp-server — internal/mcp/mcp.go
  • Problem: When MCP_TRANSPORT=http, the HTTP server at :PORT has no authentication layer. Any process that can reach the port can call all 5 MCP tools, including delete_memory.
  • Context: Currently deployed behind cluster networking; risk is limited but architectural.

Root Path / Also Serves MCP Traffic

  • Area: mnemosyne-mcp-server — internal/mcp/mcp.go
  • Problem: http.Handle("/", streamable) registers the MCP handler on both / and /mcp. Likely unintended. Clients hitting / receive MCP protocol responses instead of a 404 or health-check.

Python Tools Debt

tools/chronicler.py — Session Archiving Pipeline

  • Purpose: Scans .gemini directories for session JSON files, deduplicates by basename, copies to /workspace/chats/, and transforms to clean Markdown in /workspace/chats/md/.
  • Key features: 50 MB skip, meta-session filtering, protocol noise stripping, surgical truncation at 5000 chars.
  • Undocumented behavior: Filters sessions containing “KNOWLEDGE EXTRACTION PROTOCOL” or “CHIEF ARCHIVIST” in the first 5 messages — this heuristic is fragile and not configurable.
  • Code path: tools/chronicler.py

tools/gather_sessions.py — Simplified Session Gather

  • Purpose: Subset of chronicler.py — gather step only. Copies session/checkpoint JSONs to /workspace/chats/ with collision-safe renaming.
  • Code path: tools/gather_sessions.py

See Also

  • Parent hub: mnemosyne-mcp-server
  • Context: AGENTS.ctx/mnemosyne-mcp-server/CONTEXT.md
  • Debt register: AGENTS.ctx/memory/debts.md (TD-002)
  • Sibling topics: none yet — deepen on demand