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

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

• Semantic layer: TazLab Knowledge Layers
• Deployed through: tazlab-k8s
• Active memory complement: AGENTS.ctx
• System context: TazLab System Map

See Also

• Wiki Index