Blog / Rehber

Obsidian MCP Recipe: AI Coding Agent'e Kalıcı Hafıza

3 Mayıs 202611 dk okumaObsidianMCPDockerVS CodeMemory

Son güncelleme: Mayıs 2026

Giriş: Her Oturumda Baştan Anlatma Yorgunluğu

AI coding agent ile çalışırken en can sıkıcı noktalardan biri şu: yeni bir oturum açtığınız an agent'in hafızası sıfırlanıyor.

Dün birlikte aldığınız kararları, naming convention'ları, hangi klasörde ne yaptığınızı tekrar anlatmak zorunda kalıyorsunuz. Bir noktadan sonra geliştirmeden çok "kontekst taşıma" işi yapıyoruz.

Bu yazıda, bu sorunu Obsidian + MCP + Docker kombinasyonu ile nasıl çözdüğümüzü anlatacağım. Hem de yerelde, ek lisans maliyeti olmadan.

TL;DR

Obsidian'ı proje hafızası için ayrı bir katman olarak kullanıyoruz.
MCP server sayesinde agent bu hafızayı okuyup güncelleyebiliyor.
Repo dosyaları yine insanlara hizmet ediyor, agent hafızası Obsidian'da kalıyor.
Özellikle uzun soluklu projelerde tekrar tekrar açıklama ihtiyacını ciddi azaltıyor.

Neden Bu Yaklaşım İşe Yarıyor?

Temel fikir şu:

Repo dokümanları: Takım ve ürün için
Obsidian hafızası: Agent'in oturumlar arası çalışma hafızası için

Bunu ayırınca iki şey oluyor:

README, CHANGELOG gibi dosyalar tekrar temiz ve amacına uygun kalıyor.
Agent aynı hataları daha az tekrarlıyor, kaldığı yerden devam etmesi kolaylaşıyor.

Kısa projelerde farkı daha az hissedersiniz. Ama 10+ oturumluk işlerde bu yaklaşım gerçekten çarpan etkisi yaratıyor.

Mimariyi Basitçe Düşünelim

Sistem akışı çok karmaşık değil:

Obsidian uygulaması Mac'te çalışıyor.
Local REST API eklentisi Obsidian içeriğini HTTP ile açıyor.
Docker içindeki mcp/obsidian container'ı bu API'ye bağlanıyor.
VS Code agent'i MCP üstünden bu container ile konuşuyor.

Sonuç: Agent, proje hafıza dosyalarını okuyup güncelleyebiliyor.

Adım Adım Kurulum

1) Ön Gereksinimler

Aşağıdakiler kurulu olmalı:

Obsidian
Docker Desktop
VS Code

Docker tarafını doğrulamak için:

docker --version

2) Obsidian Vault'u Hazırlayın

Önerilen tek bir merkezi vault kullanımı:

Örnek konum: ~/ObsidianVault/DevVault
Her proje için projects/<proje-adi>/ altında klasör

Örnek hafıza dosyaları:

AGENT_CONTEXT.md
SESSION_LOG.md
TASKS.md
STRUCTURE.md

3) Local REST API Eklentisini Açın

Obsidian içinde:

Community plugins aktif edin
"Local REST API" eklentisini kurup etkinleştirin
Non-encrypted HTTP server seçeneğini açın (27123)

Bu kurulum, Docker container'ın host üzerindeki Obsidian'a sorunsuz ulaşmasını kolaylaştırıyor.

4) MCP Obsidian Container'ı Test Edin

docker pull mcp/obsidian

docker run -i --rm \
  -e OBSIDIAN_HOST=host.docker.internal \
  -e OBSIDIAN_API_KEY=YOUR_KEY \
  mcp/obsidian

Not:

host.docker.internal Mac üzerinde container'dan host'a erişim için kritik.
API key'i düz metin paylaşmayın, yerel config'te tutun.

5) VS Code MCP Konfigürasyonu

Proje içinde .vscode/mcp.json dosyasına sunucu tanımını ekleyin:

{
  "servers": {
    "obsidian": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "OBSIDIAN_HOST",
        "-e", "OBSIDIAN_API_KEY",
        "mcp/obsidian"
      ],
      "env": {
        "OBSIDIAN_HOST": "host.docker.internal",
        "OBSIDIAN_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Proje İçinde Hafıza Rolleri

Bu ayrım kritik:

AGENT_CONTEXT.md: Kalıcı gerçekler, teknik kararlar, konvansiyonlar
SESSION_LOG.md: Oturum bazlı kronolojik özet
TASKS.md: Devam eden iş listesi
STRUCTURE.md: Klasör yapısı ve önemli dosya haritası

Agent'e başlangıçta bu dosyaları okutursanız, ilk mesajdan itibaren daha doğru hareket ediyor.

Gerçek Hayatta Ne Kazandırıyor?

Aynı sprint içinde gün aşırı çalışan ekiplerde etkisi çok net:

"Geçen sefer neye karar vermiştik?" sorusu azalıyor.
Agent'in yanlış varsayımla refactor başlatma ihtimali düşüyor.
Onboarding yapan yeni geliştirici için bağlam toparlama hızlanıyor.

Özellikle "neden böyle yaptık" bilgisini saklamak için iyi bir çözüm.

Dikkat Edilmesi Gerekenler

AGENT_CONTEXT.md kısa ve güncel kalmalı; günlüğe dönmemeli.
Gizli anahtarlar hafıza notlarına yazılmamalı.
Her şeyi tek dosyaya yığmak yerine roller net tutulmalı.
Oturum kapanışında kısa bir güncelleme disiplini oturtulmalı.

Kime Uygun, Kime Değil?

Uygun:

Orta/uzun soluklu projeler
Agent ile sık iterasyon yapan ekipler
Teknik karar geçmişine ihtiyaç duyan ürünler

Daha az uygun:

1-2 oturumluk çok kısa işler
Hafıza disiplini kurulmadan "sadece araç" beklentisi olan kullanım

Sonuç

Obsidian MCP yaklaşımı, AI agent'i sihirli şekilde mükemmelleştirmiyor. Ama doğru kullanılırsa şunu sağlıyor:

Daha az tekrar
Daha iyi bağlam sürekliliği
Daha tutarlı teknik karar takibi

Kısaca: "agent'e hafıza eklemek" aslında süreç tasarımı meselesi. Obsidian + MCP bunu pratiğe dökmek için çok temiz bir yol sunuyor.