Shodh-Memory

AI ajanları ve robotlar için kalıcı bilişsel hafıza. Önemli olanı hatırla, gereksizi unut, kullanımla daha akıllı hale gel.

AI ajanları her oturumda her şeyi unutur. Robotlar misyon arasında bağlamı kaybeder. Hataları tekrarlar, desenleri kaçırır ve her etkileşimi ilk kez yapar.

Shodh-Memory bunu çözer. Gerçekten öğrenen kalıcı bir hafızadır — sık kullandığın anılar bulunması daha kolay hale gelir, eski alakasız bağlam otomatik solup gider ve bir şeyi hatırlamak ilgili şeyleri geri getirir. Chat ajanları (MCP/HTTP), robotlar (Zenoh/ROS2) ve edge cihazları için çalışır. API anahtarı yok. Bulut yok. Dış veritabanı yok. Tek binary.

Neden mem0 / Cognee / Zep Kullanmayasınız ki?

Diğer her hafıza sistemi zekayı LLM API çağrılarına devreder — bu yüzden yavaş, pahalı ve çevrimdışı çalışamaz. Shodh algoritmik zekayı kullanır: yerel embeddings, matematiksel decay, öğrenilmiş bağlantılar. Döngüde LLM yok.

Başlayalım

Birleştirilmiş CLI

# GitHub Releases'ten indir (veya brew tap varun29ankuS/shodh-memory && brew install shodh-memory)
shodh init          # İlk kurulum — config oluşturur, API anahtarı oluşturur, AI modeli indirir
shodh server        # Memory serverini :3030'da başlat
shodh setup-hooks   # Claude Code hooks kurulum talimatlarını yazdır
shodh tui           # TUI dashboard'unu başlat
shodh status        # Server sağlığını kontrol et
shodh doctor        # Sorunları teşhis et

Tek binary, tüm işlevsellik. Docker yok, API anahtarı yok, dış bağımlılık yok.

Claude Code

# 1. MCP serverini ekle (backend binary'yi otomatik indirir)
claude mcp add shodh-memory -- npx -y @shodh/memory-mcp

# 2. Otomatik hafıza yakalamayı etkinleştir (isteğe bağlı ama tavsiye edilir)
npx @shodh/memory-mcp setup-hooks

Adım 1 Claude'a kalıcı hafıza araçları verir. Adım 2, her oturumdan bağlamı otomatik olarak yakalayan Claude Code hooks kurar — hafızalar sormanda ortaya çıkar.

# 1. Serverini başlat
docker run -d -p 3030:3030 -v shodh-data:/data varunshodh/shodh-memory

# 2. Claude Code'a ekle
claude mcp add shodh-memory -- npx -y @shodh/memory-mcp

{
  "mcpServers": {
    "shodh-memory": {
      "command": "npx",
      "args": ["-y", "@shodh/memory-mcp"]
    }
  }
}

Python

pip install shodh-memory

from shodh_memory import Memory

memory = Memory(storage_path="./my_data")
memory.remember("User prefers dark mode", memory_type="Decision")
results = memory.recall("user preferences", limit=5)

Rust

[dependencies]
shodh-memory = "0.1"

use shodh_memory::{MemorySystem, MemoryConfig};

let memory = MemorySystem::new(MemoryConfig::default())?;
memory.remember("user-1", "User prefers dark mode", MemoryType::Decision, vec![])?;
let results = memory.recall("user-1", "user preferences", 5)?;

Docker

docker run -d -p 3030:3030 -v shodh-data:/data varunshodh/shodh-memory

Ne Yapar

Bir hafızayı sık kullanırsan  →  bulunması daha kolay hale gelir (Hebbian learning)
Bir hafızayı kullanmayı bırakırsan →  zamanla solup gider (activation decay)
Bir hafızayı hatırlarsın   →  ilgili hafızalar da ortaya çıkar (spreading activation)
Bir bağlantı kullanılırsa    →  kalıcı hale gelir (long-term potentiation)

Kaputun altında, hafızalar üç katman arasında akar:

Çalışan Hafıza ──overflow──▶ Oturum Hafızası ──importance──▶ Uzun Vadeli Hafıza
   (100 item)                  (100 MB)                      (RocksDB)

Bu Cowan's working memory model ve Wixted's memory decay research temeline dayanır. Sinirbilim bir hile değil — sistemin sadece veri biriktirmek yerine kullanımla neden iyileştiğinin nedeni budur.

Performans

Tek binary. GPU gerekli değil. Content-hash dedup, özdeş hafızaların asla iki kez depolanmadığını sağlar.

TUI Dashboard

shodh tui

Anlamsal hatırlama hibrit aramayla — ilgililik puanları, hafıza katmanları ve aktivite akışı

GTD görev yönetimi — projeler, yapılacaklar, yorumlar ve nedensel köken

37 MCP Aracı

Claude, Cursor ve diğer MCP istemcilerine sunulan araçların tam listesi:

REST API

http://localhost:3030 üzerinde 160+ endpoint. Tüm /api/* endpoint'leri X-API-Key başlığı gerektirir.

Tam API referansı →

# Hafıza saklama
curl -X POST http://localhost:3030/api/remember \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"user_id": "user-1", "content": "User prefers dark mode", "memory_type": "Decision"}'

# Hafızaları arama
curl -X POST http://localhost:3030/api/recall \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"user_id": "user-1", "query": "user preferences", "limit": 5}'

Robotik & ROS2

Shodh-Memory sadece chat ajanları için değil. Robotlar için kalıcı hafızadır — Spot, drone'lar, humanoidler, ROS2 veya Zenoh çalıştıran herhangi bir sistem. Bulut yok, güç döngülerini kurtarır, ödüllerden öğrenir, Zenoh'yu yerel olarak konuşur.

# Zenoh transport'unu etkinleştir (--features zenoh ile derle)
SHODH_ZENOH_ENABLED=true SHODH_ZENOH_LISTEN=tcp/0.0.0.0:7447 shodh server

# ROS2 robotları zenoh-bridge-ros2dds veya rmw_zenoh aracılığıyla bağlan — kod değişikliği yok
ros2 run zenoh_bridge_ros2dds zenoh_bridge_ros2dds

Tam kurulum ve örnekler için Robotik Hızlı Başlangıç bölümüne bakın.

Robotlar Zenoh üzerinden neler yapabilir:

Her robot anahtar segmenti olarak kendi user_id'sini kullanır (ör. shodh/spot-1/remember). robot_id filo gruplandırması için isteğe bağlı payload alanıdır.

Her Experience 26 robotiğe özgü alanı taşır: geo_location, local_position, heading, sensor_data, robot_id, mission_id, action_type, reward, terrain_type, nearby_agents, decision_context, action_params, outcome_type, confidence, hata/anomi izlemesi, kurtarma eylemleri ve tahmin öğrenmesi.

{
  "user_id": "spot-1",
  "content": "Detected crack in concrete at waypoint alpha",
  "robot_id": "spot_v2",
  "mission_id": "building_inspection_2026",
  "geo_location": [37.7749, -122.4194, 10.0],
  "local_position": [12.5, 3.2, 0.0],
  "heading": 90.0,
  "sensor_data": {"battery": 72.5, "temperature": 28.3},
  "action_type": "inspect",
  "reward": 0.9,
  "terrain_type": "indoor",
  "tags": ["crack", "concrete", "structural"]
}

{
  "user_id": "spot-1",
  "query": "structural damage near entrance",
  "mode": "spatial",
  "lat": 37.7749,
  "lon": -122.4194,
  "radius_meters": 50.0,
  "mission_id": "building_inspection_2026"
}

SHODH_ZENOH_ENABLED=true                # Zenoh transport'unu etkinleştir
SHODH_ZENOH_MODE=peer                   # peer | client | router
SHODH_ZENOH_LISTEN=tcp/0.0.0.0:7447    # Listen endpoint'leri
SHODH_ZENOH_CONNECT=tcp/1.2.3.4:7447   # Connect endpoint'leri
SHODH_ZENOH_PREFIX=shodh               # Key expression öneki

# ROS2 topic'lerine otomatik abone ol (zenoh-bridge-ros2dds üzerinden)
SHODH_ZENOH_AUTO_TOPICS='[
  {"key_expr": "rt/spot1/status", "user_id": "spot-1", "mode": "sensor"},
  {"key_expr": "rt/nav/events", "user_id": "spot-1", "mode": "event"}
]'

ROS2 Kilted (rmw_zenoh), PX4 drone'ları, Boston Dynamics Spot, humanoidler — Zenoh veya ROS2 DDS konuşan her şeyle çalışır.

Platform Desteği

Linux x86_64 · Linux ARM64 · macOS Apple Silicon · macOS Intel · Windows x86_64

Production Dağıtımı

SHODH_ENV=production              # Production modu
SHODH_API_KEYS=key1,key2,key3     # Virgülle ayrılmış API anahtarları
SHODH_HOST=127.0.0.1              # Bind adresi (varsayılan: localhost)
SHODH_PORT=3030                   # Port (varsayılan: 3030)
SHODH_MEMORY_PATH=/var/lib/shodh  # Veri dizini
SHODH_REQUEST_TIMEOUT=60          # Request zaman aşımı (saniye)
SHODH_MAX_CONCURRENT=200          # Maksimum concurrent request
SHODH_CORS_ORIGINS=https://app.example.com

services:
  shodh-memory:
    image: varunshodh/shodh-memory:latest
    environment:
      - SHODH_ENV=production
      - SHODH_HOST=0.0.0.0
      - SHODH_API_KEYS=${SHODH_API_KEYS}
    volumes:
      - shodh-data:/data
    networks:
      - internal

  caddy:
    image: caddy:latest
    ports:
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
    networks:
      - internal

volumes:
  shodh-data:

networks:
  internal:

memory.example.com {
    reverse_proxy localhost:3030
}

Topluluk

Referanslar

[1] Cowan, N. (2010). The Magical Mystery Four. Current Directions in Psychological Science. [2] Magee & Grienberger (2020). Synaptic Plasticity Forms and Functions. Annual Review of Neuroscience. [3] Subramanya et al. (2019). DiskANN. NeurIPS 2019.

Lisans

Apache 2.0

MCP Registry · Docker Hub · PyPI · npm · crates.io · Docs