# 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:

```bash
cp .env.example .env
```

Özellikle şunları ayarlayın:

- `DATABASE_URL`
- `LLM_API_KEY`
- `SHARED_HMAC_SECRET`

### 2) Docker Compose

```bash
make up
```

### 3) Migrasyonlar

```bash
make migrate
```

### 4) Testler

```bash
make test
```

## MCP Endpoint

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

Örnek:

```bash
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

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

### thread.create

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

## Örnek Tool Payloadları

### turn.ingest

```json
{
  "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

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

### retrieve.context

```json
{
  "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

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

### shared.export

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

### shared.import

```json
{
  "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.