Memory MCP

Production-grade Memory MCP server for single-tenant LibreChat workspaces. It stores raw conversation turns, distills durable memory (decisions/constraints/mistakes/assumptions/open questions), and provides hybrid retrieval plus plan consistency auditing.

Özellikler

• Raw turn log + embedding + full-text indeksleme.
• Distilled memory çıkarımı: kararlar, kısıtlar, hatalar, varsayımlar, açık sorular.
• Dedup + supersede zinciri (eski kararlar korunur, stale tespit yapılır).
• Hybrid retrieval: pgvector + PostgreSQL full-text + RRF fusion.
• Fast / Deep modlar: öngörülebilir gecikme, token budget yönetimi.
• Audit: plan/metinleri aktif karar/kısıtlar ve superseded öğelerle kontrol.
• Shared import/export: HMAC imzalı paketlerle kontrollü paylaşım.
• Gözlemlenebilirlik: JSON log + Prometheus metrikleri.

Kurulum

1) Ortam değişkenleri

.env dosyasını .env.example üzerinden oluşturun:

cp .env.example .env

Özellikle şunları ayarlayın:

• DATABASE_URL
• LLM_API_KEY
• SHARED_HMAC_SECRET

2) Docker Compose

make up

3) Migrasyonlar

make migrate

4) Testler

make test

MCP Endpoint

MCP endpointi /mcp altında çalışır. Bu servis tool + arguments ile JSON alır.

Örnek:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "thread.create",
    "arguments": {}
  }'

LibreChat MCP yapılandırması

LibreChat MCP URL’nizi şu şekilde ayarlayın:

• Uğur: https://mcp.datasins.com/mcp
• Gökçe: https://mcp.gokce.ai/mcp

Plan Registry (Topic Separation)

Planlar ayrı çalışma konuları olarak yönetilir ve her thread bir plana bağlıdır.

plan.create

{
  "tool": "plan.create",
  "arguments": {
    "name": "memory-mcp-core",
    "meta": {"owner": "ugur"}
  }
}

thread.create

{
  "tool": "thread.create",
  "arguments": {
    "plan_id": "<plan_uuid>",
    "meta": {"topic": "ingest-pipeline"}
  }
}

Örnek Tool Payloadları

turn.ingest

{
  "tool": "turn.ingest",
  "arguments": {
    "thread_id": "<uuid>",
    "role": "user",
    "text": "Yeni karar: Postgres kullanılacak.",
    "external_turn_id": "librechat-turn-123",
    "embed_now": true
  }
}

external_turn_id aynı değerle gelen tekrar çağrılarda idempotent davranır.

distill.extract

{
  "tool": "distill.extract",
  "arguments": {
    "thread_id": "<uuid>",
    "turn_id": "<uuid>",
    "include_recent_turns": 4,
    "write_to_memory": true
  }
}

retrieve.context

{
  "tool": "retrieve.context",
  "arguments": {
    "thread_id": "<uuid>",
    "query": "Hangi kararlar aktif?",
    "mode": "fast",
    "scope": "distilled_only",
    "top_k": 8,
    "token_budget": 800,
    "recency_bias": 0.1,
    "explain": true
  }
}

audit.check_consistency

{
  "tool": "audit.check_consistency",
  "arguments": {
    "thread_id": "<uuid>",
    "proposed_plan_text": "SQLite kullanalım.",
    "deep": true
  }
}

shared.export

{
  "tool": "shared.export",
  "arguments": {
    "thread_id": "<uuid>",
    "types": ["decision", "constraint"],
    "include_mistakes": false,
    "expires_in_minutes": 60
  }
}

shared.import

{
  "tool": "shared.import",
  "arguments": {
    "payload": {"...": "..."},
    "signature": "<hmac>"
  }
}

Güvenlik

• Pydantic doğrulama + sıkı enumlar.
• Prompt injection güvenliği için sistem promptlarında açık uyarı.
• HMAC imza ile export/import.
• API anahtarları loglanmaz.

Notlar

• EMBEDDING_DIM farklıysa migration güncellenmeli.
• ENABLE_LLM_RERANK=true ise low-confidence deep retrieval’da LLM rerank aktif olur.
• Retention politikaları .env içindeki RETENTION_* değişkenleriyle kontrol edilir.

LibreChat Uçtan Uca Kullanım Örnekleri

1) Yeni Plan Başlatma

1. plan.create ile yeni plan oluşturun.
2. thread.create ile plan altında bir thread açın.
3. turn.ingest ile ilk kararları gönderin.

2) Mevcut Planı Devam Ettirme

1. plan.list ile planları bulun.
2. Mevcut planın thread ID’sini takip edin veya yeni thread ekleyin.
3. distill.extract ile yeni turn’lerden karar/kısıt çıkarın.

3) Deep Audit

1. retrieve.context ile mode=deep ve explain=true kullanın.
2. audit.check_consistency ile plan metnini doğrulatın.
3. stale_references çıktısını kontrol ederek superseded kararları güncelleyin.