mnemosyne-mcp-server

Scope

This page is the repository hub for the semantic memory service.

Current Synthesis

mnemosyne-mcp-server/ is a Go MCP server that provides semantic memory ingestion, retrieval, listing, and deletion backed by Postgres plus vector search. It is the semantic retrieval layer of TazLab and is deployed in the cluster as mnemosyne-mcp.

Repository Structure

mnemosyne-mcp-server/
├── cmd/mnemosyne-mcp/main.go     # Entrypoint: env parsing, DB init, transport selection
├── internal/
│   ├── mcp/mcp.go                # MCP server, 5 tool handlers, HTTP/stdio transport
│   ├── logic/logic.go            # Business logic: async ingestion, dedup, search
│   ├── embedding/embedding.go    # Gemini embedding client (REST API)
│   └── db/db.go                  # PostgreSQL + pgvector layer
├── tools/
│   ├── chronicler.py             # Session archiving pipeline
│   ├── gather_sessions.py        # Simplified session gather
│   └── requirements.txt          # Python dependencies
├── Dockerfile                    # Multi-stage build (golang → distroless)
├── .github/workflows/publish.yml # CI: build + push to Docker Hub
├── test_mcp_client.py            # Manual MCP test client
└── mnemosyne-mcp                 # Pre-compiled binary

Quick Facts

MCP Client Usage (curl / bash)

La sessione si inizializza via POST /mcp/initialize, non via POST /mcp diretto. Il server restituisce Mcp-Session-Id negli header HTTP.

MCP="http://192.168.1.240:8004/mcp"

# 1. Initialize session (legge session ID dagli header)
INIT=$(curl -s -D - -X POST "${MCP}/initialize" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"client","version":"1.0"}}}')
SID=$(echo "$INIT" | grep -i "Mcp-Session-Id" | awk '{print $2}' | tr -d '\r')

# 2. Ingest memoria
curl -s -X POST "${MCP}/tools/call" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: ${SID}" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ingest_memory","arguments":{"content":"...","timestamp":"2026-06-04T09:00:00Z"}}}'

# 3. List memorie recenti
curl -s -X POST "${MCP}/tools/call" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: ${SID}" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_memories","arguments":{"limit":5}}}'

Il path include il metodo MCP (/tools/call, /tools/list, /initialize), non solo /mcp. L’header Mcp-Session-Id va passato a ogni richiesta dopo l’initialize.

Main Responsibilities

• expose MCP tools for memory CRUD and semantic retrieval
• generate Gemini embeddings and persist memory records
• serve either stdio or HTTP (with SSE streaming disabled) transport modes
• act as the retrieval service behind the mnemosyne knowledge layer

Important Operational Characteristics

• uses gemini-embedding-001
• assumes an external memories table exists
• follows GitOps deployment through image build plus Flux reconciliation rather than manual deployment

Coexistence with Hindsight

Hindsight (entity hub) is the new multi-agent memory platform in adoption (architecture): LLM fact extraction, 4-strategy recall fused via RRF, memory banks, directives, mental models. The CRISP project memory-migration-hindsight is migrating this service’s 745 memories (2024: 36, 2025: 61, 2026: 648) plus chronicles, reports, and doctrine into the Hindsight bank tazlab-common — including the correction of LLM-hallucinated years in Mnemosyne timestamps (e.g. “2024-05” clusters are really Jan–Feb 2026, proven via git tags and vault chat files).

Until the migration sign-off:

• Mnemosyne remains active as the legacy read-only retrieval layer — no new writes are routed to it during migration
• Hindsight is the target memory layer (MCP http://192.168.1.240:8006/mcp/{bank_id}/), already consumed for recall alongside Mnemosyne
• Deployment reality: Mnemosyne serves 3072-dim vectors on 192.168.1.240:8004; Hindsight shares the same MetalLB IP via port 8006
• Post-sign-off decommission of Mnemosyne is a separate future project — this service is not deprecated yet

Canonical Starting Pages for Agents

Architecture & Design

• Architecture — Component map, data flow, transport modes, design decisions
• Database Schema — memories table, dimension auto-detection, pgvector queries
• Embedding Model — Gemini API integration, TD-002 dimension mismatch

Tools & Operations

• MCP Tools — All 5 tool schemas and parameters
• Async Ingestion — Background worker, dedup, silent failure risks

Details (Implementation)

• Ingest Memory Detail — Exact step-by-step ingestion pipeline
• Retrieve Memories Detail — Semantic search flow and temporal filter gap
• Deployment Detail — Docker pipeline, env vars, Flux automation, cluster manifests
• Python Tools Detail — chronicler.py and gather_sessions.py

Known Issues

• Known Issues & Technical Debt — TD-002 and code-level gaps

Relationships

• Successor (in adoption): Hindsight — multi-agent memory layer, migration of this service’s corpus in progress
• Semantic layer: TazLab Knowledge Layers
• Deployed through: tazlab-k8s
• Active memory complement: AGENTS.ctx
• System context: TazLab System Map

See Also

• Wiki Index