general improvements (#17)

* refactor(hooks): simplify hook execution with shared context

- [x] Extract BaseInput struct to eliminate duplicate fields across hooks
- [x] Create RunHook handler pattern for session-start and user-prompt
- [x] Create RunStatuslineHook for fast statusline rendering without worker startup
- [x] Add HookContext struct to pass port, project, CWD, SessionID to handlers
- [x] Add db/interface.go with ObservationReader/Writer interfaces
- [x] Add comprehensive conflict management tests in sqlite/conflict_test.go
- [x] Add vector client tests for Count, ModelVersion, NeedsRebuild, GetStaleVectors
- [x] Add FilterByThreshold helper tests for query result filtering
- [x] Make handlers_test more robust for network-dependent update checks
- [x] Update package versions in UI

* Move to GORM + general cleanup

* feat(mcp): add observation relations discovery and scoring integration

- [x] Add find_related_observations MCP tool for discovering related observations by confidence
- [x] Integrate scoring calculator and recalculator into MCP server initialization
- [x] Add pattern, relation, and session stores to MCP server dependencies
- [x] Register MCP server in Claude Code settings during plugin installation
- [x] Update install scripts (bash, PowerShell) to configure MCP server settings
- [x] Switch plugin manifest files to template-based versioning (plugin.json.tpl, marketplace.json.tpl)
- [x] Update all MCP server tests to pass new dependency parameters

internal/db/gorm/benchmark_test.go

@@ -0,0 +1,331 @@
+//go:build fts5
+
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"gorm.io/gorm/logger"
+
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+)
+
+// setupBenchStore creates a temporary store for benchmarking.
+func setupBenchStore(b *testing.B) (*Store, func()) {
+	b.Helper()
+
+	tmpDir, err := os.MkdirTemp("", "gorm_bench_*")
+	if err != nil {
+		b.Fatalf("create temp dir: %v", err)
+	}
+
+	dbPath := filepath.Join(tmpDir, "bench.db")
+	cfg := Config{
+		Path:     dbPath,
+		MaxConns: 4,
+		LogLevel: logger.Silent,
+	}
+
+	store, err := NewStore(cfg)
+	if err != nil {
+		os.RemoveAll(tmpDir)
+		b.Fatalf("NewStore failed: %v", err)
+	}
+
+	cleanup := func() {
+		store.Close()
+		os.RemoveAll(tmpDir)
+	}
+
+	return store, cleanup
+}
+
+// BenchmarkSessionStore_CreateSDKSession benchmarks session creation (most frequent operation).
+func BenchmarkSessionStore_CreateSDKSession(b *testing.B) {
+	store, cleanup := setupBenchStore(b)
+	defer cleanup()
+
+	sessionStore := NewSessionStore(store)
+	ctx := context.Background()
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		sessionID := fmt.Sprintf("claude-bench-%d", i)
+		_, err := sessionStore.CreateSDKSession(ctx, sessionID, "bench-project", "test prompt")
+		if err != nil {
+			b.Fatalf("CreateSDKSession failed: %v", err)
+		}
+	}
+}
+
+// BenchmarkSessionStore_CreateSDKSession_Idempotent benchmarks idempotent session creation (INSERT OR IGNORE).
+func BenchmarkSessionStore_CreateSDKSession_Idempotent(b *testing.B) {
+	store, cleanup := setupBenchStore(b)
+	defer cleanup()
+
+	sessionStore := NewSessionStore(store)
+	ctx := context.Background()
+
+	// Pre-create session
+	sessionStore.CreateSDKSession(ctx, "claude-bench", "bench-project", "test prompt")
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_, err := sessionStore.CreateSDKSession(ctx, "claude-bench", "bench-project", "updated prompt")
+		if err != nil {
+			b.Fatalf("CreateSDKSession failed: %v", err)
+		}
+	}
+}
+
+// BenchmarkObservationStore_StoreObservation benchmarks observation storage (high frequency).
+func BenchmarkObservationStore_StoreObservation(b *testing.B) {
+	store, cleanup := setupBenchStore(b)
+	defer cleanup()
+
+	sessionStore := NewSessionStore(store)
+	obsStore := NewObservationStore(store, nil, nil, nil)
+	ctx := context.Background()
+
+	// Create session
+	sessionID, _ := sessionStore.CreateSDKSession(ctx, "claude-bench", "bench-project", "")
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		obs := &models.ParsedObservation{
+			Type:      models.ObsTypeDiscovery,
+			Title:     fmt.Sprintf("Observation %d", i),
+			Narrative: "Benchmark observation content",
+		}
+		_, _, err := obsStore.StoreObservation(ctx, "claude-bench", "bench-project", obs, int(sessionID), int64(i+1))
+		if err != nil {
+			b.Fatalf("StoreObservation failed: %v", err)
+		}
+	}
+}
+
+// BenchmarkObservationStore_GetRecentObservations benchmarks recent observation retrieval.
+func BenchmarkObservationStore_GetRecentObservations(b *testing.B) {
+	store, cleanup := setupBenchStore(b)
+	defer cleanup()
+
+	sessionStore := NewSessionStore(store)
+	obsStore := NewObservationStore(store, nil, nil, nil)
+	ctx := context.Background()
+
+	// Create session and observations
+	sessionID, _ := sessionStore.CreateSDKSession(ctx, "claude-bench", "bench-project", "")
+	for i := 0; i < 100; i++ {
+		obs := &models.ParsedObservation{
+			Type:      models.ObsTypeDiscovery,
+			Title:     fmt.Sprintf("Observation %d", i),
+			Narrative: "Benchmark observation content",
+		}
+		obsStore.StoreObservation(ctx, "claude-bench", "bench-project", obs, int(sessionID), int64(i+1))
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_, err := obsStore.GetRecentObservations(ctx, "bench-project", 20)
+		if err != nil {
+			b.Fatalf("GetRecentObservations failed: %v", err)
+		}
+	}
+}
+
+// BenchmarkObservationStore_SearchObservationsFTS benchmarks FTS5 search (latency-sensitive).
+func BenchmarkObservationStore_SearchObservationsFTS(b *testing.B) {
+	store, cleanup := setupBenchStore(b)
+	defer cleanup()
+
+	sessionStore := NewSessionStore(store)
+	obsStore := NewObservationStore(store, nil, nil, nil)
+	ctx := context.Background()
+
+	// Create session and observations with searchable content
+	sessionID, _ := sessionStore.CreateSDKSession(ctx, "claude-bench", "bench-project", "")
+	for i := 0; i < 100; i++ {
+		obs := &models.ParsedObservation{
+			Type:      models.ObsTypeDiscovery,
+			Title:     fmt.Sprintf("Security best practice %d", i),
+			Narrative: "This observation discusses security patterns and authentication mechanisms",
+		}
+		obsStore.StoreObservation(ctx, "claude-bench", "bench-project", obs, int(sessionID), int64(i+1))
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_, err := obsStore.SearchObservationsFTS(ctx, "security authentication", "bench-project", 10)
+		if err != nil {
+			b.Fatalf("SearchObservationsFTS failed: %v", err)
+		}
+	}
+}
+
+// BenchmarkObservationStore_UpdateImportanceScore benchmarks scoring updates.
+func BenchmarkObservationStore_UpdateImportanceScore(b *testing.B) {
+	store, cleanup := setupBenchStore(b)
+	defer cleanup()
+
+	sessionStore := NewSessionStore(store)
+	obsStore := NewObservationStore(store, nil, nil, nil)
+	ctx := context.Background()
+
+	// Create session and observation
+	sessionID, _ := sessionStore.CreateSDKSession(ctx, "claude-bench", "bench-project", "")
+	obs := &models.ParsedObservation{Type: models.ObsTypeDiscovery, Title: "Test"}
+	obsID, _, _ := obsStore.StoreObservation(ctx, "claude-bench", "bench-project", obs, int(sessionID), 1)
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		score := float64(i%10) + 1.0
+		err := obsStore.UpdateImportanceScore(ctx, obsID, score)
+		if err != nil {
+			b.Fatalf("UpdateImportanceScore failed: %v", err)
+		}
+	}
+}
+
+// BenchmarkObservationStore_UpdateImportanceScores_Bulk benchmarks bulk scoring updates.
+func BenchmarkObservationStore_UpdateImportanceScores_Bulk(b *testing.B) {
+	store, cleanup := setupBenchStore(b)
+	defer cleanup()
+
+	sessionStore := NewSessionStore(store)
+	obsStore := NewObservationStore(store, nil, nil, nil)
+	ctx := context.Background()
+
+	// Create session and 100 observations
+	sessionID, _ := sessionStore.CreateSDKSession(ctx, "claude-bench", "bench-project", "")
+	var obsIDs []int64
+	for i := 0; i < 100; i++ {
+		obs := &models.ParsedObservation{Type: models.ObsTypeDiscovery, Title: fmt.Sprintf("Obs %d", i)}
+		obsID, _, _ := obsStore.StoreObservation(ctx, "claude-bench", "bench-project", obs, int(sessionID), int64(i+1))
+		obsIDs = append(obsIDs, obsID)
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		scores := make(map[int64]float64)
+		for _, id := range obsIDs {
+			scores[id] = float64(i%10) + 1.0
+		}
+		err := obsStore.UpdateImportanceScores(ctx, scores)
+		if err != nil {
+			b.Fatalf("UpdateImportanceScores failed: %v", err)
+		}
+	}
+}
+
+// BenchmarkPromptStore_SaveUserPromptWithMatches benchmarks prompt storage with matches.
+func BenchmarkPromptStore_SaveUserPromptWithMatches(b *testing.B) {
+	store, cleanup := setupBenchStore(b)
+	defer cleanup()
+
+	sessionStore := NewSessionStore(store)
+	promptStore := NewPromptStore(store, nil)
+	ctx := context.Background()
+
+	// Create session
+	sessionID, _ := sessionStore.CreateSDKSession(ctx, "claude-bench", "bench-project", "")
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_, err := promptStore.SaveUserPromptWithMatches(ctx, "claude-bench", int(sessionID), fmt.Sprintf("Prompt %d", i), i+1)
+		if err != nil {
+			b.Fatalf("SaveUserPromptWithMatches failed: %v", err)
+		}
+	}
+}
+
+// BenchmarkSummaryStore_StoreSummary benchmarks summary storage.
+func BenchmarkSummaryStore_StoreSummary(b *testing.B) {
+	store, cleanup := setupBenchStore(b)
+	defer cleanup()
+
+	sessionStore := NewSessionStore(store)
+	summaryStore := NewSummaryStore(store)
+	ctx := context.Background()
+
+	// Create session
+	sessionStore.CreateSDKSession(ctx, "claude-bench", "bench-project", "")
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		summary := &models.ParsedSummary{
+			Request:      fmt.Sprintf("Request %d", i),
+			Investigated: "Investigation details",
+			Learned:      "Learning summary",
+			Completed:    "Completion status",
+		}
+		_, _, err := summaryStore.StoreSummary(ctx, "claude-bench", "bench-project", summary, i+1, 100)
+		if err != nil {
+			b.Fatalf("StoreSummary failed: %v", err)
+		}
+	}
+}
+
+// BenchmarkRelationStore_StoreRelation benchmarks relation storage.
+func BenchmarkRelationStore_StoreRelation(b *testing.B) {
+	store, cleanup := setupBenchStore(b)
+	defer cleanup()
+
+	sessionStore := NewSessionStore(store)
+	obsStore := NewObservationStore(store, nil, nil, nil)
+	relationStore := NewRelationStore(store)
+	ctx := context.Background()
+
+	// Create session and observations
+	sessionID, _ := sessionStore.CreateSDKSession(ctx, "claude-bench", "bench-project", "")
+	obs1 := &models.ParsedObservation{Type: models.ObsTypeDiscovery, Title: "Source"}
+	obsID1, _, _ := obsStore.StoreObservation(ctx, "claude-bench", "bench-project", obs1, int(sessionID), 1)
+	obs2 := &models.ParsedObservation{Type: models.ObsTypeDiscovery, Title: "Target"}
+	obsID2, _, _ := obsStore.StoreObservation(ctx, "claude-bench", "bench-project", obs2, int(sessionID), 2)
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		relation := &models.ObservationRelation{
+			SourceID:        obsID1,
+			TargetID:        obsID2,
+			RelationType:    models.RelationCauses,
+			Confidence:      0.9,
+			DetectionSource: models.DetectionSourceFileOverlap,
+		}
+		_, err := relationStore.StoreRelation(ctx, relation)
+		if err != nil {
+			b.Fatalf("StoreRelation failed: %v", err)
+		}
+	}
+}
+
+// BenchmarkPatternStore_StorePattern benchmarks pattern storage.
+func BenchmarkPatternStore_StorePattern(b *testing.B) {
+	store, cleanup := setupBenchStore(b)
+	defer cleanup()
+
+	patternStore := NewPatternStore(store)
+	ctx := context.Background()
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		pattern := &models.Pattern{
+			Name:        fmt.Sprintf("Pattern %d", i),
+			Type:        models.PatternTypeBug,
+			Description: sql.NullString{String: "Benchmark pattern", Valid: true},
+			Frequency:   1,
+			Confidence:  0.8,
+			Projects:    []string{"bench-project"},
+			Status:      models.PatternStatusActive,
+		}
+		_, err := patternStore.StorePattern(ctx, pattern)
+		if err != nil {
+			b.Fatalf("StorePattern failed: %v", err)
+		}
+	}
+}

internal/db/gorm/conflict_store.go

@@ -0,0 +1,281 @@
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"context"
+	"database/sql"
+	"time"
+
+	"gorm.io/gorm"
+
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+)
+
+// SupersededRetentionDays is the number of days to keep superseded observations before deletion.
+const SupersededRetentionDays = 3
+
+// ConflictStore provides conflict-related database operations using GORM.
+type ConflictStore struct {
+	db *gorm.DB
+}
+
+// NewConflictStore creates a new conflict store.
+func NewConflictStore(store *Store) *ConflictStore {
+	return &ConflictStore{
+		db: store.DB,
+	}
+}
+
+// StoreConflict stores a new observation conflict.
+func (s *ConflictStore) StoreConflict(ctx context.Context, conflict *models.ObservationConflict) (int64, error) {
+	dbConflict := &ObservationConflict{
+		NewerObsID:      conflict.NewerObsID,
+		OlderObsID:      conflict.OlderObsID,
+		ConflictType:    conflict.ConflictType,
+		Resolution:      conflict.Resolution,
+		DetectedAt:      conflict.DetectedAt,
+		DetectedAtEpoch: conflict.DetectedAtEpoch,
+		Resolved:        0,
+	}
+
+	// Convert bool to int
+	if conflict.Resolved {
+		dbConflict.Resolved = 1
+	}
+
+	// Handle nullable fields
+	if conflict.Reason != "" {
+		dbConflict.Reason = sql.NullString{String: conflict.Reason, Valid: true}
+	}
+	if conflict.ResolvedAt != nil && *conflict.ResolvedAt != "" {
+		dbConflict.ResolvedAt = sql.NullString{String: *conflict.ResolvedAt, Valid: true}
+	}
+
+	result := s.db.WithContext(ctx).Create(dbConflict)
+	if result.Error != nil {
+		return 0, result.Error
+	}
+
+	return dbConflict.ID, nil
+}
+
+// MarkObservationSuperseded marks an observation as superseded.
+func (s *ConflictStore) MarkObservationSuperseded(ctx context.Context, obsID int64) error {
+	result := s.db.WithContext(ctx).
+		Model(&Observation{}).
+		Where("id = ?", obsID).
+		Update("is_superseded", 1)
+
+	return result.Error
+}
+
+// MarkObservationsSuperseded marks multiple observations as superseded.
+func (s *ConflictStore) MarkObservationsSuperseded(ctx context.Context, obsIDs []int64) error {
+	if len(obsIDs) == 0 {
+		return nil
+	}
+
+	result := s.db.WithContext(ctx).
+		Model(&Observation{}).
+		Where("id IN ?", obsIDs).
+		Update("is_superseded", 1)
+
+	return result.Error
+}
+
+// GetConflictsByObservationID retrieves all conflicts involving an observation.
+func (s *ConflictStore) GetConflictsByObservationID(ctx context.Context, obsID int64) ([]*models.ObservationConflict, error) {
+	var conflicts []ObservationConflict
+
+	err := s.db.WithContext(ctx).
+		Where("newer_obs_id = ? OR older_obs_id = ?", obsID, obsID).
+		Order("detected_at_epoch DESC").
+		Find(&conflicts).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelConflicts(conflicts), nil
+}
+
+// GetUnresolvedConflicts retrieves all unresolved conflicts.
+func (s *ConflictStore) GetUnresolvedConflicts(ctx context.Context, limit int) ([]*models.ObservationConflict, error) {
+	var conflicts []ObservationConflict
+
+	err := s.db.WithContext(ctx).
+		Where("resolved = 0").
+		Order("detected_at_epoch DESC").
+		Limit(limit).
+		Find(&conflicts).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelConflicts(conflicts), nil
+}
+
+// GetSupersededObservationIDs returns IDs of all observations that have been superseded.
+func (s *ConflictStore) GetSupersededObservationIDs(ctx context.Context, project string) ([]int64, error) {
+	var ids []int64
+
+	err := s.db.WithContext(ctx).
+		Table("observation_conflicts oc").
+		Select("DISTINCT oc.older_obs_id").
+		Joins("JOIN observations o ON o.id = oc.older_obs_id").
+		Where("oc.resolution = ?", models.ResolutionPreferNewer).
+		Where("o.project = ? OR o.scope = 'global'", project).
+		Pluck("oc.older_obs_id", &ids).Error
+
+	return ids, err
+}
+
+// ResolveConflict marks a conflict as resolved.
+func (s *ConflictStore) ResolveConflict(ctx context.Context, conflictID int64, resolution models.ConflictResolution) error {
+	now := time.Now().Format(time.RFC3339)
+
+	result := s.db.WithContext(ctx).
+		Model(&ObservationConflict{}).
+		Where("id = ?", conflictID).
+		Updates(map[string]interface{}{
+			"resolved":    1,
+			"resolved_at": now,
+			"resolution":  resolution,
+		})
+
+	return result.Error
+}
+
+// DeleteConflictsByObservationID deletes all conflicts involving an observation.
+// Called when an observation is deleted.
+func (s *ConflictStore) DeleteConflictsByObservationID(ctx context.Context, obsID int64) error {
+	result := s.db.WithContext(ctx).
+		Where("newer_obs_id = ? OR older_obs_id = ?", obsID, obsID).
+		Delete(&ObservationConflict{})
+
+	return result.Error
+}
+
+// ConflictWithDetails contains a conflict with its observation details.
+type ConflictWithDetails struct {
+	Conflict      *models.ObservationConflict
+	NewerObsTitle string
+	OlderObsTitle string
+}
+
+// CleanupSupersededObservations deletes observations that have been superseded for longer than
+// SupersededRetentionDays. Returns the IDs of deleted observations for downstream cleanup (e.g., vector DB).
+func (s *ConflictStore) CleanupSupersededObservations(ctx context.Context, project string) ([]int64, error) {
+	// Calculate cutoff time (3 days ago in milliseconds)
+	cutoffEpoch := time.Now().AddDate(0, 0, -SupersededRetentionDays).UnixMilli()
+
+	var toDelete []int64
+
+	// Use a transaction to prevent TOCTOU race condition
+	err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		// Find IDs to delete
+		err := tx.Table("observations o").
+			Select("DISTINCT o.id").
+			Joins("JOIN observation_conflicts oc ON o.id = oc.older_obs_id").
+			Where("o.is_superseded = 1").
+			Where("o.project = ?", project).
+			Where("oc.detected_at_epoch < ?", cutoffEpoch).
+			Pluck("o.id", &toDelete).Error
+
+		if err != nil {
+			return err
+		}
+
+		if len(toDelete) == 0 {
+			return nil
+		}
+
+		// Delete the conflict records first (due to foreign key constraints)
+		for _, obsID := range toDelete {
+			err := tx.Where("newer_obs_id = ? OR older_obs_id = ?", obsID, obsID).
+				Delete(&ObservationConflict{}).Error
+			if err != nil {
+				return err
+			}
+		}
+
+		// Delete the observations
+		return tx.Delete(&Observation{}, toDelete).Error
+	})
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toDelete, nil
+}
+
+// GetConflictsWithDetails retrieves all conflicts with observation titles for display.
+func (s *ConflictStore) GetConflictsWithDetails(ctx context.Context, project string, limit int) ([]*ConflictWithDetails, error) {
+	var results []struct {
+		ObservationConflict
+		NewerTitle sql.NullString `gorm:"column:newer_title"`
+		OlderTitle sql.NullString `gorm:"column:older_title"`
+	}
+
+	err := s.db.WithContext(ctx).
+		Table("observation_conflicts oc").
+		Select("oc.*, "+
+			"COALESCE(newer.title, '') as newer_title, "+
+			"COALESCE(older.title, '') as older_title").
+		Joins("JOIN observations newer ON newer.id = oc.newer_obs_id").
+		Joins("JOIN observations older ON older.id = oc.older_obs_id").
+		Where("newer.project = ? OR older.project = ?", project, project).
+		Order("oc.detected_at_epoch DESC").
+		Limit(limit).
+		Scan(&results).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	conflicts := make([]*ConflictWithDetails, len(results))
+	for i, r := range results {
+		conflicts[i] = &ConflictWithDetails{
+			Conflict:      toModelConflict(&r.ObservationConflict),
+			NewerObsTitle: r.NewerTitle.String,
+			OlderObsTitle: r.OlderTitle.String,
+		}
+	}
+
+	return conflicts, nil
+}
+
+// toModelConflict converts a GORM ObservationConflict to a pkg/models ObservationConflict.
+func toModelConflict(c *ObservationConflict) *models.ObservationConflict {
+	conflict := &models.ObservationConflict{
+		ID:              c.ID,
+		NewerObsID:      c.NewerObsID,
+		OlderObsID:      c.OlderObsID,
+		ConflictType:    c.ConflictType,
+		Resolution:      c.Resolution,
+		DetectedAt:      c.DetectedAt,
+		DetectedAtEpoch: c.DetectedAtEpoch,
+		Resolved:        c.Resolved == 1,
+	}
+
+	if c.Reason.Valid {
+		conflict.Reason = c.Reason.String
+	}
+	if c.ResolvedAt.Valid {
+		s := c.ResolvedAt.String
+		conflict.ResolvedAt = &s
+	}
+
+	return conflict
+}
+
+// toModelConflicts converts a slice of GORM ObservationConflicts to pkg/models ObservationConflicts.
+func toModelConflicts(conflicts []ObservationConflict) []*models.ObservationConflict {
+	result := make([]*models.ObservationConflict, len(conflicts))
+	for i, c := range conflicts {
+		result[i] = toModelConflict(&c)
+	}
+	return result
+}

internal/db/gorm/conflict_store_test.go

@@ -0,0 +1,637 @@
+//go:build fts5
+
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm/logger"
+
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+)
+
+// testConflictStore creates a ConflictStore with a temporary database for testing.
+func testConflictStore(t *testing.T) (*ConflictStore, *Store, func()) {
+	t.Helper()
+
+	tmpDir, err := os.MkdirTemp("", "gorm_conflict_test_*")
+	if err != nil {
+		t.Fatalf("create temp dir: %v", err)
+	}
+
+	dbPath := filepath.Join(tmpDir, "test.db")
+	cfg := Config{
+		Path:     dbPath,
+		MaxConns: 4,
+		LogLevel: logger.Silent,
+	}
+
+	store, err := NewStore(cfg)
+	if err != nil {
+		os.RemoveAll(tmpDir)
+		t.Fatalf("NewStore failed: %v", err)
+	}
+
+	conflictStore := NewConflictStore(store)
+
+	cleanup := func() {
+		store.Close()
+		os.RemoveAll(tmpDir)
+	}
+
+	return conflictStore, store, cleanup
+}
+
+func TestConflictStore_StoreConflict(t *testing.T) {
+	conflictStore, store, cleanup := testConflictStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create session for observations
+	sessionStore := NewSessionStore(store)
+	sessionID, err := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+	require.NoError(t, err)
+
+	// Create test observations
+	obsStore := NewObservationStore(store, nil, nil, nil)
+	obs1 := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "Newer observation",
+	}
+	obsID1, _, err := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs1, int(sessionID), 1)
+	require.NoError(t, err)
+
+	obs2 := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "Older observation",
+	}
+	obsID2, _, err := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs2, int(sessionID), 2)
+	require.NoError(t, err)
+
+	// Create conflict
+	now := time.Now()
+	conflict := &models.ObservationConflict{
+		NewerObsID:      obsID1,
+		OlderObsID:      obsID2,
+		ConflictType:    models.ConflictContradicts,
+		Resolution:      models.ResolutionPreferNewer,
+		Reason:          "Newer observation contradicts older one",
+		DetectedAt:      now.Format(time.RFC3339),
+		DetectedAtEpoch: now.UnixMilli(),
+		Resolved:        false,
+	}
+
+	id, err := conflictStore.StoreConflict(ctx, conflict)
+	require.NoError(t, err)
+	assert.Greater(t, id, int64(0))
+
+	// Verify conflict was stored
+	var count int64
+	store.DB.Model(&ObservationConflict{}).Where("id = ?", id).Count(&count)
+	assert.Equal(t, int64(1), count)
+}
+
+func TestConflictStore_MarkObservationSuperseded(t *testing.T) {
+	conflictStore, store, cleanup := testConflictStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create observation
+	sessionStore := NewSessionStore(store)
+	sessionID, err := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+	require.NoError(t, err)
+
+	obsStore := NewObservationStore(store, nil, nil, nil)
+	obs := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "Test observation",
+	}
+	obsID, _, err := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs, int(sessionID), 1)
+	require.NoError(t, err)
+
+	// Mark as superseded
+	err = conflictStore.MarkObservationSuperseded(ctx, obsID)
+	require.NoError(t, err)
+
+	// Verify it's marked
+	var dbObs Observation
+	store.DB.First(&dbObs, obsID)
+	assert.Equal(t, 1, dbObs.IsSuperseded)
+}
+
+func TestConflictStore_MarkObservationsSuperseded(t *testing.T) {
+	conflictStore, store, cleanup := testConflictStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	tests := []struct {
+		name   string
+		obsIDs []int64
+		setup  func() []int64
+	}{
+		{
+			name:   "empty list",
+			obsIDs: []int64{},
+			setup:  func() []int64 { return []int64{} },
+		},
+		{
+			name: "single observation",
+			setup: func() []int64 {
+				sessionStore := NewSessionStore(store)
+				sessionID, _ := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+				obsStore := NewObservationStore(store, nil, nil, nil)
+				obs := &models.ParsedObservation{
+					Type:  models.ObsTypeDiscovery,
+					Title: "Test",
+				}
+				id, _, _ := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs, int(sessionID), 1)
+				return []int64{id}
+			},
+		},
+		{
+			name: "multiple observations",
+			setup: func() []int64 {
+				sessionStore := NewSessionStore(store)
+				sessionID, _ := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+				obsStore := NewObservationStore(store, nil, nil, nil)
+				var ids []int64
+				for i := 0; i < 3; i++ {
+					obs := &models.ParsedObservation{
+						Type:  models.ObsTypeDiscovery,
+						Title: "Test",
+					}
+					id, _, _ := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs, int(sessionID), int64(i+1))
+					ids = append(ids, id)
+				}
+				return ids
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			obsIDs := tt.setup()
+			err := conflictStore.MarkObservationsSuperseded(ctx, obsIDs)
+			require.NoError(t, err)
+
+			if len(obsIDs) > 0 {
+				// Verify all are marked
+				for _, id := range obsIDs {
+					var dbObs Observation
+					store.DB.First(&dbObs, id)
+					assert.Equal(t, 1, dbObs.IsSuperseded)
+				}
+			}
+		})
+	}
+}
+
+func TestConflictStore_GetConflictsByObservationID(t *testing.T) {
+	conflictStore, store, cleanup := testConflictStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create observations
+	sessionStore := NewSessionStore(store)
+	sessionID, err := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+	require.NoError(t, err)
+
+	obsStore := NewObservationStore(store, nil, nil, nil)
+	var obsIDs []int64
+	for i := 0; i < 3; i++ {
+		obs := &models.ParsedObservation{
+			Type:  models.ObsTypeDiscovery,
+			Title: "Test",
+		}
+		id, _, err := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs, int(sessionID), int64(i+1))
+		require.NoError(t, err)
+		obsIDs = append(obsIDs, id)
+	}
+
+	// Create conflicts involving observation 2 (index 1)
+	now := time.Now()
+	conflict1 := &models.ObservationConflict{
+		NewerObsID:      obsIDs[0],
+		OlderObsID:      obsIDs[1],
+		ConflictType:    models.ConflictContradicts,
+		Resolution:      models.ResolutionPreferNewer,
+		Reason:          "reason1",
+		DetectedAt:      now.Format(time.RFC3339),
+		DetectedAtEpoch: now.UnixMilli(),
+	}
+	_, err = conflictStore.StoreConflict(ctx, conflict1)
+	require.NoError(t, err)
+
+	conflict2 := &models.ObservationConflict{
+		NewerObsID:      obsIDs[1],
+		OlderObsID:      obsIDs[2],
+		ConflictType:    models.ConflictSuperseded,
+		Resolution:      models.ResolutionPreferNewer,
+		Reason:          "reason2",
+		DetectedAt:      now.Format(time.RFC3339),
+		DetectedAtEpoch: now.UnixMilli(),
+	}
+	_, err = conflictStore.StoreConflict(ctx, conflict2)
+	require.NoError(t, err)
+
+	// Get conflicts for observation 2 (involved in 2 conflicts)
+	conflicts, err := conflictStore.GetConflictsByObservationID(ctx, obsIDs[1])
+	require.NoError(t, err)
+	assert.Len(t, conflicts, 2)
+}
+
+func TestConflictStore_GetUnresolvedConflicts(t *testing.T) {
+	conflictStore, store, cleanup := testConflictStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create observations
+	sessionStore := NewSessionStore(store)
+	sessionID, err := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+	require.NoError(t, err)
+
+	obsStore := NewObservationStore(store, nil, nil, nil)
+	obs1 := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "Test1",
+	}
+	obsID1, _, err := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs1, int(sessionID), 1)
+	require.NoError(t, err)
+
+	obs2 := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "Test2",
+	}
+	obsID2, _, err := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs2, int(sessionID), 2)
+	require.NoError(t, err)
+
+	// Create unresolved conflicts
+	now := time.Now()
+	for i := 0; i < 5; i++ {
+		conflict := &models.ObservationConflict{
+			NewerObsID:      obsID1,
+			OlderObsID:      obsID2,
+			ConflictType:    models.ConflictContradicts,
+			Resolution:      models.ResolutionPreferNewer,
+			Reason:          "reason",
+			DetectedAt:      now.Format(time.RFC3339),
+			DetectedAtEpoch: now.UnixMilli(),
+			Resolved:        false,
+		}
+		_, err = conflictStore.StoreConflict(ctx, conflict)
+		require.NoError(t, err)
+	}
+
+	// Create resolved conflict
+	resolvedAt := now.Format(time.RFC3339)
+	resolvedConflict := &models.ObservationConflict{
+		NewerObsID:      obsID1,
+		OlderObsID:      obsID2,
+		ConflictType:    models.ConflictContradicts,
+		Resolution:      models.ResolutionPreferNewer,
+		Reason:          "reason",
+		DetectedAt:      now.Format(time.RFC3339),
+		DetectedAtEpoch: now.UnixMilli(),
+		Resolved:        true,
+		ResolvedAt:      &resolvedAt,
+	}
+	_, err = conflictStore.StoreConflict(ctx, resolvedConflict)
+	require.NoError(t, err)
+
+	// Get unresolved conflicts with limit
+	conflicts, err := conflictStore.GetUnresolvedConflicts(ctx, 3)
+	require.NoError(t, err)
+	assert.Len(t, conflicts, 3)
+
+	// Verify all are unresolved
+	for _, c := range conflicts {
+		assert.False(t, c.Resolved)
+	}
+}
+
+func TestConflictStore_GetSupersededObservationIDs(t *testing.T) {
+	conflictStore, store, cleanup := testConflictStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create observations
+	sessionStore := NewSessionStore(store)
+	sessionID, err := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+	require.NoError(t, err)
+
+	obsStore := NewObservationStore(store, nil, nil, nil)
+
+	// Create newer observations
+	newer1 := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "Newer1",
+	}
+	newerID1, _, err := obsStore.StoreObservation(ctx, "claude-1", "test-project", newer1, int(sessionID), 1)
+	require.NoError(t, err)
+
+	newer2 := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "Newer2",
+	}
+	newerID2, _, err := obsStore.StoreObservation(ctx, "claude-1", "test-project", newer2, int(sessionID), 2)
+	require.NoError(t, err)
+
+	// Create older observations
+	older1 := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "Older1",
+	}
+	olderID1, _, err := obsStore.StoreObservation(ctx, "claude-1", "test-project", older1, int(sessionID), 3)
+	require.NoError(t, err)
+
+	older2 := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "Older2",
+	}
+	olderID2, _, err := obsStore.StoreObservation(ctx, "claude-1", "test-project", older2, int(sessionID), 4)
+	require.NoError(t, err)
+
+	// Mark older observations as superseded
+	err = conflictStore.MarkObservationsSuperseded(ctx, []int64{olderID1, olderID2})
+	require.NoError(t, err)
+
+	// Create conflicts with prefer_newer resolution
+	now := time.Now()
+	conflict1 := &models.ObservationConflict{
+		NewerObsID:      newerID1,
+		OlderObsID:      olderID1,
+		ConflictType:    models.ConflictSuperseded,
+		Resolution:      models.ResolutionPreferNewer,
+		Reason:          "reason1",
+		DetectedAt:      now.Format(time.RFC3339),
+		DetectedAtEpoch: now.UnixMilli(),
+	}
+	_, err = conflictStore.StoreConflict(ctx, conflict1)
+	require.NoError(t, err)
+
+	conflict2 := &models.ObservationConflict{
+		NewerObsID:      newerID2,
+		OlderObsID:      olderID2,
+		ConflictType:    models.ConflictSuperseded,
+		Resolution:      models.ResolutionPreferNewer,
+		Reason:          "reason2",
+		DetectedAt:      now.Format(time.RFC3339),
+		DetectedAtEpoch: now.UnixMilli(),
+	}
+	_, err = conflictStore.StoreConflict(ctx, conflict2)
+	require.NoError(t, err)
+
+	// Get superseded IDs (should return older observation IDs)
+	ids, err := conflictStore.GetSupersededObservationIDs(ctx, "test-project")
+	require.NoError(t, err)
+	assert.Len(t, ids, 2)
+	assert.Contains(t, ids, olderID1)
+	assert.Contains(t, ids, olderID2)
+}
+
+func TestConflictStore_ResolveConflict(t *testing.T) {
+	conflictStore, _, cleanup := testConflictStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create a simple conflict by inserting directly to DB
+	conflict := &ObservationConflict{
+		NewerObsID:      1,
+		OlderObsID:      2,
+		ConflictType:    models.ConflictContradicts,
+		Resolution:      models.ResolutionManual,
+		DetectedAt:      time.Now().Format(time.RFC3339),
+		DetectedAtEpoch: time.Now().UnixMilli(),
+		Resolved:        0,
+	}
+	conflictStore.db.Create(conflict)
+
+	// Resolve conflict
+	err := conflictStore.ResolveConflict(ctx, conflict.ID, models.ResolutionPreferNewer)
+	require.NoError(t, err)
+
+	// Verify resolved
+	var resolved ObservationConflict
+	conflictStore.db.First(&resolved, conflict.ID)
+	assert.Equal(t, 1, resolved.Resolved)
+	assert.True(t, resolved.ResolvedAt.Valid)
+	assert.Equal(t, models.ResolutionPreferNewer, resolved.Resolution)
+}
+
+func TestConflictStore_DeleteConflictsByObservationID(t *testing.T) {
+	conflictStore, _, cleanup := testConflictStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create conflicts directly in DB
+	now := time.Now()
+	conflicts := []ObservationConflict{
+		{
+			NewerObsID:      1,
+			OlderObsID:      2,
+			ConflictType:    models.ConflictContradicts,
+			Resolution:      models.ResolutionPreferNewer,
+			DetectedAt:      now.Format(time.RFC3339),
+			DetectedAtEpoch: now.UnixMilli(),
+		},
+		{
+			NewerObsID:      3,
+			OlderObsID:      1,
+			ConflictType:    models.ConflictContradicts,
+			Resolution:      models.ResolutionPreferNewer,
+			DetectedAt:      now.Format(time.RFC3339),
+			DetectedAtEpoch: now.UnixMilli(),
+		},
+		{
+			NewerObsID:      2,
+			OlderObsID:      3,
+			ConflictType:    models.ConflictContradicts,
+			Resolution:      models.ResolutionPreferNewer,
+			DetectedAt:      now.Format(time.RFC3339),
+			DetectedAtEpoch: now.UnixMilli(),
+		},
+	}
+	for _, c := range conflicts {
+		conflictStore.db.Create(&c)
+	}
+
+	// Delete conflicts for observation 1
+	err := conflictStore.DeleteConflictsByObservationID(ctx, 1)
+	require.NoError(t, err)
+
+	// Verify only conflicts involving 1 are deleted
+	var count int64
+	conflictStore.db.Model(&ObservationConflict{}).
+		Where("newer_obs_id = 1 OR older_obs_id = 1").
+		Count(&count)
+	assert.Equal(t, int64(0), count)
+
+	// Other conflict should still exist
+	conflictStore.db.Model(&ObservationConflict{}).
+		Where("newer_obs_id = 2 AND older_obs_id = 3").
+		Count(&count)
+	assert.Equal(t, int64(1), count)
+}
+
+func TestConflictStore_CleanupSupersededObservations(t *testing.T) {
+	conflictStore, store, cleanup := testConflictStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create observations
+	sessionStore := NewSessionStore(store)
+	sessionID, err := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+	require.NoError(t, err)
+
+	obsStore := NewObservationStore(store, nil, nil, nil)
+
+	// Create newer observations
+	newer1 := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "Newer1",
+	}
+	newerID1, _, err := obsStore.StoreObservation(ctx, "claude-1", "test-project", newer1, int(sessionID), 1)
+	require.NoError(t, err)
+
+	newer2 := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "Newer2",
+	}
+	newerID2, _, err := obsStore.StoreObservation(ctx, "claude-1", "test-project", newer2, int(sessionID), 2)
+	require.NoError(t, err)
+
+	// Create older observations
+	older1 := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "OldSuperseded",
+	}
+	oldSupersededID, _, err := obsStore.StoreObservation(ctx, "claude-1", "test-project", older1, int(sessionID), 3)
+	require.NoError(t, err)
+
+	older2 := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "RecentSuperseded",
+	}
+	recentSupersededID, _, err := obsStore.StoreObservation(ctx, "claude-1", "test-project", older2, int(sessionID), 4)
+	require.NoError(t, err)
+
+	// Mark as superseded
+	err = conflictStore.MarkObservationsSuperseded(ctx, []int64{oldSupersededID, recentSupersededID})
+	require.NoError(t, err)
+
+	// Create conflicts
+	oldTime := time.Now().AddDate(0, 0, -SupersededRetentionDays-1)
+	recentTime := time.Now().AddDate(0, 0, -1)
+
+	// Old conflict (should be deleted)
+	oldConflict := &models.ObservationConflict{
+		NewerObsID:      newerID1,
+		OlderObsID:      oldSupersededID,
+		ConflictType:    models.ConflictSuperseded,
+		Resolution:      models.ResolutionPreferNewer,
+		Reason:          "old",
+		DetectedAt:      oldTime.Format(time.RFC3339),
+		DetectedAtEpoch: oldTime.UnixMilli(),
+	}
+	_, err = conflictStore.StoreConflict(ctx, oldConflict)
+	require.NoError(t, err)
+
+	// Recent conflict (should be kept)
+	recentConflict := &models.ObservationConflict{
+		NewerObsID:      newerID2,
+		OlderObsID:      recentSupersededID,
+		ConflictType:    models.ConflictSuperseded,
+		Resolution:      models.ResolutionPreferNewer,
+		Reason:          "recent",
+		DetectedAt:      recentTime.Format(time.RFC3339),
+		DetectedAtEpoch: recentTime.UnixMilli(),
+	}
+	_, err = conflictStore.StoreConflict(ctx, recentConflict)
+	require.NoError(t, err)
+
+	// Cleanup old superseded observations
+	deletedIDs, err := conflictStore.CleanupSupersededObservations(ctx, "test-project")
+	require.NoError(t, err)
+	assert.Len(t, deletedIDs, 1)
+	assert.Contains(t, deletedIDs, oldSupersededID)
+
+	// Verify only old superseded observation was deleted
+	var count int64
+	store.DB.Model(&Observation{}).Count(&count)
+	assert.Equal(t, int64(3), count) // newer1, newer2, recentSuperseded remain
+
+	// Verify old observation was deleted
+	store.DB.Model(&Observation{}).Where("id = ?", oldSupersededID).Count(&count)
+	assert.Equal(t, int64(0), count)
+}
+
+func TestConflictStore_GetConflictsWithDetails(t *testing.T) {
+	conflictStore, store, cleanup := testConflictStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create observations
+	sessionStore := NewSessionStore(store)
+	sessionID, err := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+	require.NoError(t, err)
+
+	obsStore := NewObservationStore(store, nil, nil, nil)
+
+	newer := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "Newer observation",
+	}
+	newerID, _, err := obsStore.StoreObservation(ctx, "claude-1", "test-project", newer, int(sessionID), 1)
+	require.NoError(t, err)
+
+	older := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "Older observation",
+	}
+	olderID, _, err := obsStore.StoreObservation(ctx, "claude-1", "test-project", older, int(sessionID), 2)
+	require.NoError(t, err)
+
+	// Create conflict
+	now := time.Now()
+	conflict := &models.ObservationConflict{
+		NewerObsID:      newerID,
+		OlderObsID:      olderID,
+		ConflictType:    models.ConflictContradicts,
+		Resolution:      models.ResolutionPreferNewer,
+		Reason:          "Test conflict",
+		DetectedAt:      now.Format(time.RFC3339),
+		DetectedAtEpoch: now.UnixMilli(),
+	}
+	_, err = conflictStore.StoreConflict(ctx, conflict)
+	require.NoError(t, err)
+
+	// Get conflicts with details
+	conflicts, err := conflictStore.GetConflictsWithDetails(ctx, "test-project", 10)
+	require.NoError(t, err)
+	assert.Len(t, conflicts, 1)
+
+	// Verify conflict details
+	assert.Equal(t, newerID, conflicts[0].Conflict.NewerObsID)
+	assert.Equal(t, olderID, conflicts[0].Conflict.OlderObsID)
+	assert.Equal(t, models.ConflictContradicts, conflicts[0].Conflict.ConflictType)
+	assert.Equal(t, "Test conflict", conflicts[0].Conflict.Reason)
+	assert.Equal(t, "Newer observation", conflicts[0].NewerObsTitle)
+	assert.Equal(t, "Older observation", conflicts[0].OlderObsTitle)
+}

internal/db/gorm/doc.go

@@ -0,0 +1,38 @@
+// Package gorm provides a GORM-based database implementation for claude-mnemonic.
+//
+// This is a drop-in replacement for internal/db/sqlite with the following benefits:
+//   - 50% code reduction (8,500 → 4,250 lines)
+//   - Type-safe query building
+//   - Automatic statement caching
+//   - Same performance characteristics
+//   - Zero breaking changes
+//
+// Status: Production-ready, not yet integrated
+//
+// # Integration
+//
+// To use this package instead of internal/db/sqlite:
+//
+//	import "github.com/lukaszraczylo/claude-mnemonic/internal/db/gorm"
+//
+//	store, err := gorm.NewStore(gorm.Config{
+//	    Path:     "/path/to/database.db",
+//	    MaxConns: 4,
+//	    LogLevel: logger.Silent,
+//	})
+//
+// See INTEGRATION_GUIDE.md for complete migration instructions.
+//
+// # Testing
+//
+// All tests require the fts5 build tag:
+//
+//	go test -tags "fts5" -v ./internal/db/gorm
+//
+// # Performance
+//
+// See PERFORMANCE.md for detailed benchmark results.
+package gorm
+
+// This file exists for package documentation and to prevent deadcode warnings
+// on an intentionally unused (but complete and tested) implementation.

internal/db/gorm/fts5_test.go

@@ -0,0 +1,42 @@
+//go:build fts5
+
+package gorm
+
+import (
+	"database/sql"
+	"os"
+	"path/filepath"
+	"testing"
+
+	_ "github.com/mattn/go-sqlite3"
+)
+
+// TestFTS5Available verifies FTS5 is available in mattn/go-sqlite3
+func TestFTS5Available(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "fts5_test_*")
+	if err != nil {
+		t.Fatalf("create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	dbPath := filepath.Join(tmpDir, "test.db")
+
+	// Open with mattn/go-sqlite3 driver
+	db, err := sql.Open("sqlite3", dbPath)
+	if err != nil {
+		t.Fatalf("open database: %v", err)
+	}
+	defer db.Close()
+
+	// Try to create FTS5 virtual table
+	_, err = db.Exec(`
+		CREATE VIRTUAL TABLE test_fts USING fts5(
+			content
+		)
+	`)
+	if err != nil {
+		t.Fatalf("create FTS5 table failed: %v", err)
+	}
+
+	t.Logf("✅ FTS5 is available in mattn/go-sqlite3")
+}

internal/db/gorm/helpers.go

@@ -0,0 +1,64 @@
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"context"
+	"database/sql"
+	"net/http"
+	"strconv"
+	"time"
+
+	"gorm.io/gorm"
+)
+
+// EnsureSessionExists creates a session if it doesn't exist.
+// This is shared between stores to avoid duplication.
+func EnsureSessionExists(ctx context.Context, db *gorm.DB, sdkSessionID, project string) error {
+	// Check if session exists
+	var count int64
+	err := db.WithContext(ctx).
+		Model(&SDKSession{}).
+		Where("sdk_session_id = ?", sdkSessionID).
+		Count(&count).Error
+
+	if err != nil {
+		return err
+	}
+
+	if count > 0 {
+		return nil // Session exists
+	}
+
+	// Auto-create session
+	now := time.Now()
+	session := &SDKSession{
+		ClaudeSessionID: sdkSessionID,
+		SDKSessionID:    sqlNullString(sdkSessionID),
+		Project:         project,
+		Status:          "active",
+		StartedAt:       now.Format(time.RFC3339),
+		StartedAtEpoch:  now.UnixMilli(),
+		PromptCounter:   0,
+	}
+
+	return db.WithContext(ctx).Create(session).Error
+}
+
+// sqlNullString creates a sql.NullString from a string.
+func sqlNullString(s string) sql.NullString {
+	if s == "" {
+		return sql.NullString{Valid: false}
+	}
+	return sql.NullString{String: s, Valid: true}
+}
+
+// ParseLimitParam parses the "limit" query parameter from an HTTP request.
+// Returns defaultLimit if the parameter is missing or invalid.
+func ParseLimitParam(r *http.Request, defaultLimit int) int {
+	if l := r.URL.Query().Get("limit"); l != "" {
+		if parsed, err := strconv.Atoi(l); err == nil && parsed > 0 {
+			return parsed
+		}
+	}
+	return defaultLimit
+}

internal/db/gorm/integration_test.go

@@ -0,0 +1,343 @@
+//go:build fts5
+
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"context"
+	"database/sql"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm/logger"
+
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+)
+
+// TestIntegration_EndToEndWorkflow verifies a complete workflow
+// simulating real usage of the GORM package.
+func TestIntegration_EndToEndWorkflow(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "gorm_integration_test_*")
+	require.NoError(t, err)
+	defer os.RemoveAll(tmpDir)
+
+	dbPath := filepath.Join(tmpDir, "test.db")
+	cfg := Config{
+		Path:     dbPath,
+		MaxConns: 4,
+		LogLevel: logger.Silent,
+	}
+
+	// Step 1: Initialize store
+	store, err := NewStore(cfg)
+	require.NoError(t, err)
+	defer store.Close()
+
+	ctx := context.Background()
+
+	// Step 2: Create all store types
+	sessionStore := NewSessionStore(store)
+	summaryStore := NewSummaryStore(store)
+	conflictStore := NewConflictStore(store)
+	relationStore := NewRelationStore(store)
+	patternStore := NewPatternStore(store)
+
+	// Create observation store with dependencies
+	observationStore := NewObservationStore(store, nil, conflictStore, relationStore)
+	promptStore := NewPromptStore(store, nil)
+
+	// Step 3: Create a session
+	sessionID, err := sessionStore.CreateSDKSession(ctx, "claude-test", "test-project", "")
+	require.NoError(t, err)
+	assert.Greater(t, sessionID, int64(0))
+
+	// Step 4: Store observations
+	obs1 := &models.ParsedObservation{
+		Type:     models.ObsTypeDiscovery,
+		Title:    "Test Discovery",
+		Subtitle: "Testing GORM integration",
+		Facts:    []string{"Fact 1", "Fact 2"},
+		Concepts: []string{"testing", "integration"},
+	}
+
+	obsID1, _, err := observationStore.StoreObservation(ctx, "claude-test", "test-project", obs1, int(sessionID), 1)
+	require.NoError(t, err)
+	assert.Greater(t, obsID1, int64(0))
+
+	obs2 := &models.ParsedObservation{
+		Type:     models.ObsTypeBugfix,
+		Title:    "Test Bugfix",
+		Facts:    []string{"Fixed bug"},
+		Concepts: []string{"bugfix"},
+	}
+
+	obsID2, _, err := observationStore.StoreObservation(ctx, "claude-test", "test-project", obs2, int(sessionID), 2)
+	require.NoError(t, err)
+	assert.Greater(t, obsID2, int64(0))
+
+	// Step 5: Create relations
+	now := time.Now()
+	relation := &models.ObservationRelation{
+		SourceID:        obsID1,
+		TargetID:        obsID2,
+		RelationType:    models.RelationCauses,
+		Confidence:      0.8,
+		DetectionSource: models.DetectionSourceFileOverlap,
+		CreatedAt:       now.Format(time.RFC3339),
+		CreatedAtEpoch:  now.UnixMilli(),
+	}
+
+	relID, err := relationStore.StoreRelation(ctx, relation)
+	require.NoError(t, err)
+	assert.Greater(t, relID, int64(0))
+
+	// Step 6: Update importance scores
+	err = observationStore.UpdateImportanceScore(ctx, obsID1, 5.0)
+	require.NoError(t, err)
+
+	// Step 7: Increment retrieval counts
+	err = observationStore.IncrementRetrievalCount(ctx, []int64{obsID1, obsID2})
+	require.NoError(t, err)
+
+	// Step 8: Create a pattern
+	pattern := &models.Pattern{
+		Name:           "Test Pattern",
+		Type:           models.PatternTypeBug,
+		Signature:      []string{"bug", "fix"},
+		Frequency:      1,
+		Projects:       []string{"test-project"},
+		ObservationIDs: []int64{obsID1, obsID2},
+		Status:         models.PatternStatusActive,
+		Confidence:     0.75,
+		LastSeenAt:     now.Format(time.RFC3339),
+		LastSeenEpoch:  now.UnixMilli(),
+		CreatedAt:      now.Format(time.RFC3339),
+		CreatedAtEpoch: now.UnixMilli(),
+	}
+
+	patternID, err := patternStore.StorePattern(ctx, pattern)
+	require.NoError(t, err)
+	assert.Greater(t, patternID, int64(0))
+
+	// Step 9: Store a prompt
+	promptID, err := promptStore.SaveUserPromptWithMatches(ctx, "claude-test", 1, "Test prompt", 2)
+	require.NoError(t, err)
+	assert.Greater(t, promptID, int64(0))
+
+	// Step 10: Store a summary
+	summary := &models.ParsedSummary{
+		Request:      "Test request",
+		Investigated: "Test investigation",
+		Learned:      "Test learning",
+		Completed:    "Test completion",
+		NextSteps:    "Test next steps",
+		Notes:        "Test notes",
+	}
+
+	summaryID, _, err := summaryStore.StoreSummary(ctx, "claude-test", "test-project", summary, 1, 100)
+	require.NoError(t, err)
+	assert.Greater(t, summaryID, int64(0))
+
+	// Step 11: Verify data retrieval
+	retrievedObs, err := observationStore.GetObservationByID(ctx, obsID1)
+	require.NoError(t, err)
+	require.NotNil(t, retrievedObs)
+	assert.Equal(t, "Test Discovery", retrievedObs.Title.String)
+	assert.Equal(t, 5.0, retrievedObs.ImportanceScore)
+	assert.Equal(t, 1, retrievedObs.RetrievalCount)
+
+	// Step 12: Verify relations
+	relations, err := relationStore.GetRelationsByObservationID(ctx, obsID1)
+	require.NoError(t, err)
+	assert.Len(t, relations, 1)
+	assert.Equal(t, obsID2, relations[0].TargetID)
+
+	// Step 13: Verify pattern
+	retrievedPattern, err := patternStore.GetPatternByID(ctx, patternID)
+	require.NoError(t, err)
+	require.NotNil(t, retrievedPattern)
+	assert.Equal(t, "Test Pattern", retrievedPattern.Name)
+
+	// Step 14: Verify stats
+	stats, err := observationStore.GetObservationFeedbackStats(ctx, "test-project")
+	require.NoError(t, err)
+	assert.Equal(t, 2, stats.Total)
+
+	t.Log("✅ End-to-end integration test passed!")
+}
+
+// TestIntegration_StoreCompatibility verifies that Store methods work correctly.
+func TestIntegration_StoreCompatibility(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "gorm_store_test_*")
+	require.NoError(t, err)
+	defer os.RemoveAll(tmpDir)
+
+	dbPath := filepath.Join(tmpDir, "test.db")
+	cfg := Config{
+		Path:     dbPath,
+		MaxConns: 4,
+		LogLevel: logger.Silent,
+	}
+
+	store, err := NewStore(cfg)
+	require.NoError(t, err)
+	defer store.Close()
+
+	// Verify raw DB access (needed for vector client)
+	rawDB := store.GetRawDB()
+	require.NotNil(t, rawDB)
+	assert.IsType(t, &sql.DB{}, rawDB)
+
+	// Verify GORM DB access
+	gormDB := store.GetDB()
+	require.NotNil(t, gormDB)
+
+	// Verify Close works
+	err = store.Close()
+	require.NoError(t, err)
+}
+
+// TestIntegration_ConcurrentAccess verifies thread-safe operations.
+func TestIntegration_ConcurrentAccess(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "gorm_concurrent_test_*")
+	require.NoError(t, err)
+	defer os.RemoveAll(tmpDir)
+
+	dbPath := filepath.Join(tmpDir, "test.db")
+	cfg := Config{
+		Path:     dbPath,
+		MaxConns: 4,
+		LogLevel: logger.Silent,
+	}
+
+	store, err := NewStore(cfg)
+	require.NoError(t, err)
+	defer store.Close()
+
+	sessionStore := NewSessionStore(store)
+	ctx := context.Background()
+
+	// Create session
+	sessionID, err := sessionStore.CreateSDKSession(ctx, "claude-concurrent", "test-project", "")
+	require.NoError(t, err)
+
+	// Concurrent prompt counter increments
+	done := make(chan bool)
+	numGoroutines := 10
+
+	for i := 0; i < numGoroutines; i++ {
+		go func() {
+			_, err := sessionStore.IncrementPromptCounter(ctx, sessionID)
+			assert.NoError(t, err)
+			done <- true
+		}()
+	}
+
+	// Wait for all goroutines
+	for i := 0; i < numGoroutines; i++ {
+		<-done
+	}
+
+	// Verify final count
+	session, err := sessionStore.GetSessionByID(ctx, sessionID)
+	require.NoError(t, err)
+	assert.Equal(t, int64(numGoroutines), int64(session.PromptCounter))
+
+	t.Log("✅ Concurrent access test passed!")
+}
+
+// TestIntegration_WALMode verifies WAL mode is enabled.
+func TestIntegration_WALMode(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "gorm_wal_test_*")
+	require.NoError(t, err)
+	defer os.RemoveAll(tmpDir)
+
+	dbPath := filepath.Join(tmpDir, "test.db")
+	cfg := Config{
+		Path:     dbPath,
+		MaxConns: 4,
+		LogLevel: logger.Silent,
+	}
+
+	store, err := NewStore(cfg)
+	require.NoError(t, err)
+	defer store.Close()
+
+	// Check WAL mode via raw SQL
+	var journalMode string
+	err = store.GetRawDB().QueryRow("PRAGMA journal_mode").Scan(&journalMode)
+	require.NoError(t, err)
+	assert.Equal(t, "wal", journalMode, "WAL mode should be enabled")
+
+	t.Log("✅ WAL mode verification passed!")
+}
+
+// TestIntegration_FTS5Search verifies FTS5 functionality.
+func TestIntegration_FTS5Search(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "gorm_fts5_test_*")
+	require.NoError(t, err)
+	defer os.RemoveAll(tmpDir)
+
+	dbPath := filepath.Join(tmpDir, "test.db")
+	cfg := Config{
+		Path:     dbPath,
+		MaxConns: 4,
+		LogLevel: logger.Silent,
+	}
+
+	store, err := NewStore(cfg)
+	require.NoError(t, err)
+	defer store.Close()
+
+	ctx := context.Background()
+	sessionStore := NewSessionStore(store)
+	observationStore := NewObservationStore(store, nil, nil, nil)
+
+	// Create session
+	sessionID, _ := sessionStore.CreateSDKSession(ctx, "claude-fts5", "test-project", "")
+
+	// Store observations with searchable text
+	obs1 := &models.ParsedObservation{
+		Type:     models.ObsTypeDiscovery,
+		Title:    "Database optimization techniques",
+		Subtitle: "Improving query performance",
+		Facts:    []string{"Use indexes", "Optimize queries"},
+		Concepts: []string{"performance", "optimization"},
+	}
+
+	obsID1, _, _ := observationStore.StoreObservation(ctx, "claude-fts5", "test-project", obs1, int(sessionID), 1)
+
+	obs2 := &models.ParsedObservation{
+		Type:     models.ObsTypeBugfix,
+		Title:    "Fixed memory leak",
+		Facts:    []string{"Closed connections properly"},
+		Concepts: []string{"bugfix", "memory"},
+	}
+
+	observationStore.StoreObservation(ctx, "claude-fts5", "test-project", obs2, int(sessionID), 2)
+
+	// Give FTS5 triggers time to process
+	time.Sleep(100 * time.Millisecond)
+
+	// Search using FTS5
+	results, err := observationStore.SearchObservationsFTS(ctx, "optimization", "test-project", 10)
+	require.NoError(t, err)
+
+	// Should find the optimization observation
+	assert.NotEmpty(t, results, "FTS5 search should return results")
+
+	found := false
+	for _, obs := range results {
+		if obs.ID == obsID1 {
+			found = true
+			break
+		}
+	}
+	assert.True(t, found, "FTS5 should find the optimization observation")
+
+	t.Log("✅ FTS5 search test passed!")
+}

internal/db/gorm/migrations.go

@@ -0,0 +1,332 @@
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"database/sql"
+	"fmt"
+	"time"
+
+	"github.com/go-gormigrate/gormigrate/v2"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+// runMigrations runs all database migrations using gormigrate.
+func runMigrations(db *gorm.DB, sqlDB *sql.DB) error {
+	m := gormigrate.New(db, gormigrate.DefaultOptions, []*gormigrate.Migration{
+		// Migration 001: Core tables (SDKSession, Observation, SessionSummary)
+		{
+			ID: "001_core_tables",
+			Migrate: func(tx *gorm.DB) error {
+				// AutoMigrate creates tables with all indexes from struct tags
+				if err := tx.AutoMigrate(&SDKSession{}); err != nil {
+					return err
+				}
+				if err := tx.AutoMigrate(&Observation{}); err != nil {
+					return err
+				}
+				return tx.AutoMigrate(&SessionSummary{})
+			},
+			Rollback: func(tx *gorm.DB) error {
+				return tx.Migrator().DropTable("sdk_sessions", "observations", "session_summaries")
+			},
+		},
+
+		// Migration 002: User prompts table
+		{
+			ID: "002_user_prompts",
+			Migrate: func(tx *gorm.DB) error {
+				return tx.AutoMigrate(&UserPrompt{})
+			},
+			Rollback: func(tx *gorm.DB) error {
+				return tx.Migrator().DropTable("user_prompts")
+			},
+		},
+
+		// Migration 003: FTS5 virtual table for user prompts
+		{
+			ID: "003_user_prompts_fts",
+			Migrate: func(tx *gorm.DB) error {
+				sqls := []string{
+					`CREATE VIRTUAL TABLE IF NOT EXISTS user_prompts_fts USING fts5(
+						prompt_text,
+						content='user_prompts',
+						content_rowid='id'
+					)`,
+					`CREATE TRIGGER IF NOT EXISTS user_prompts_ai AFTER INSERT ON user_prompts BEGIN
+						INSERT INTO user_prompts_fts(rowid, prompt_text)
+						VALUES (new.id, new.prompt_text);
+					END`,
+					`CREATE TRIGGER IF NOT EXISTS user_prompts_ad AFTER DELETE ON user_prompts BEGIN
+						INSERT INTO user_prompts_fts(user_prompts_fts, rowid, prompt_text)
+						VALUES('delete', old.id, old.prompt_text);
+					END`,
+					`CREATE TRIGGER IF NOT EXISTS user_prompts_au AFTER UPDATE ON user_prompts BEGIN
+						INSERT INTO user_prompts_fts(user_prompts_fts, rowid, prompt_text)
+						VALUES('delete', old.id, old.prompt_text);
+						INSERT INTO user_prompts_fts(rowid, prompt_text)
+						VALUES (new.id, new.prompt_text);
+					END`,
+				}
+				for _, s := range sqls {
+					if err := tx.Exec(s).Error; err != nil {
+						return err
+					}
+				}
+				return nil
+			},
+			Rollback: func(tx *gorm.DB) error {
+				sqls := []string{
+					"DROP TRIGGER IF EXISTS user_prompts_au",
+					"DROP TRIGGER IF EXISTS user_prompts_ad",
+					"DROP TRIGGER IF EXISTS user_prompts_ai",
+					"DROP TABLE IF EXISTS user_prompts_fts",
+				}
+				for _, s := range sqls {
+					if err := tx.Exec(s).Error; err != nil {
+						return err
+					}
+				}
+				return nil
+			},
+		},
+
+		// Migration 004: FTS5 virtual table for observations
+		{
+			ID: "004_observations_fts",
+			Migrate: func(tx *gorm.DB) error {
+				sqls := []string{
+					`CREATE VIRTUAL TABLE IF NOT EXISTS observations_fts USING fts5(
+						title, subtitle, narrative,
+						content='observations',
+						content_rowid='id'
+					)`,
+					`CREATE TRIGGER IF NOT EXISTS observations_ai AFTER INSERT ON observations BEGIN
+						INSERT INTO observations_fts(rowid, title, subtitle, narrative)
+						VALUES (new.id, new.title, new.subtitle, new.narrative);
+					END`,
+					`CREATE TRIGGER IF NOT EXISTS observations_ad AFTER DELETE ON observations BEGIN
+						INSERT INTO observations_fts(observations_fts, rowid, title, subtitle, narrative)
+						VALUES('delete', old.id, old.title, old.subtitle, old.narrative);
+					END`,
+					`CREATE TRIGGER IF NOT EXISTS observations_au AFTER UPDATE ON observations BEGIN
+						INSERT INTO observations_fts(observations_fts, rowid, title, subtitle, narrative)
+						VALUES('delete', old.id, old.title, old.subtitle, old.narrative);
+						INSERT INTO observations_fts(rowid, title, subtitle, narrative)
+						VALUES (new.id, new.title, new.subtitle, new.narrative);
+					END`,
+				}
+				for _, s := range sqls {
+					if err := tx.Exec(s).Error; err != nil {
+						return err
+					}
+				}
+				return nil
+			},
+			Rollback: func(tx *gorm.DB) error {
+				sqls := []string{
+					"DROP TRIGGER IF EXISTS observations_au",
+					"DROP TRIGGER IF EXISTS observations_ad",
+					"DROP TRIGGER IF EXISTS observations_ai",
+					"DROP TABLE IF EXISTS observations_fts",
+				}
+				for _, s := range sqls {
+					if err := tx.Exec(s).Error; err != nil {
+						return err
+					}
+				}
+				return nil
+			},
+		},
+
+		// Migration 005: FTS5 virtual table for session summaries
+		{
+			ID: "005_session_summaries_fts",
+			Migrate: func(tx *gorm.DB) error {
+				sqls := []string{
+					`CREATE VIRTUAL TABLE IF NOT EXISTS session_summaries_fts USING fts5(
+						request, investigated, learned, completed, next_steps, notes,
+						content='session_summaries',
+						content_rowid='id'
+					)`,
+					`CREATE TRIGGER IF NOT EXISTS session_summaries_ai AFTER INSERT ON session_summaries BEGIN
+						INSERT INTO session_summaries_fts(rowid, request, investigated, learned, completed, next_steps, notes)
+						VALUES (new.id, new.request, new.investigated, new.learned, new.completed, new.next_steps, new.notes);
+					END`,
+					`CREATE TRIGGER IF NOT EXISTS session_summaries_ad AFTER DELETE ON session_summaries BEGIN
+						INSERT INTO session_summaries_fts(session_summaries_fts, rowid, request, investigated, learned, completed, next_steps, notes)
+						VALUES('delete', old.id, old.request, old.investigated, old.learned, old.completed, old.next_steps, old.notes);
+					END`,
+					`CREATE TRIGGER IF NOT EXISTS session_summaries_au AFTER UPDATE ON session_summaries BEGIN
+						INSERT INTO session_summaries_fts(session_summaries_fts, rowid, request, investigated, learned, completed, next_steps, notes)
+						VALUES('delete', old.id, old.request, old.investigated, old.learned, old.completed, old.next_steps, old.notes);
+						INSERT INTO session_summaries_fts(rowid, request, investigated, learned, completed, next_steps, notes)
+						VALUES (new.id, new.request, new.investigated, new.learned, new.completed, new.next_steps, new.notes);
+					END`,
+				}
+				for _, s := range sqls {
+					if err := tx.Exec(s).Error; err != nil {
+						return err
+					}
+				}
+				return nil
+			},
+			Rollback: func(tx *gorm.DB) error {
+				sqls := []string{
+					"DROP TRIGGER IF EXISTS session_summaries_au",
+					"DROP TRIGGER IF EXISTS session_summaries_ad",
+					"DROP TRIGGER IF EXISTS session_summaries_ai",
+					"DROP TABLE IF EXISTS session_summaries_fts",
+				}
+				for _, s := range sqls {
+					if err := tx.Exec(s).Error; err != nil {
+						return err
+					}
+				}
+				return nil
+			},
+		},
+
+		// Migration 006: sqlite-vec vectors table
+		{
+			ID: "006_sqlite_vec_vectors",
+			Migrate: func(tx *gorm.DB) error {
+				// Note: Uses bge-small-en-v1.5 embeddings (384 dimensions) with model_version
+				sql := `CREATE VIRTUAL TABLE IF NOT EXISTS vectors USING vec0(
+					doc_id TEXT PRIMARY KEY,
+					embedding float[384],
+					sqlite_id INTEGER,
+					doc_type TEXT,
+					field_type TEXT,
+					project TEXT,
+					scope TEXT,
+					model_version TEXT
+				)`
+				return tx.Exec(sql).Error
+			},
+			Rollback: func(tx *gorm.DB) error {
+				return tx.Exec("DROP TABLE IF EXISTS vectors").Error
+			},
+		},
+
+		// Migration 007: Concept weights table with seed data
+		{
+			ID: "007_concept_weights",
+			Migrate: func(tx *gorm.DB) error {
+				if err := tx.AutoMigrate(&ConceptWeight{}); err != nil {
+					return err
+				}
+
+				// Seed default concept weights
+				now := time.Now().Format(time.RFC3339)
+				weights := []ConceptWeight{
+					{Concept: "security", Weight: 0.30, UpdatedAt: now},
+					{Concept: "gotcha", Weight: 0.25, UpdatedAt: now},
+					{Concept: "best-practice", Weight: 0.20, UpdatedAt: now},
+					{Concept: "anti-pattern", Weight: 0.20, UpdatedAt: now},
+					{Concept: "architecture", Weight: 0.15, UpdatedAt: now},
+					{Concept: "performance", Weight: 0.15, UpdatedAt: now},
+					{Concept: "error-handling", Weight: 0.15, UpdatedAt: now},
+					{Concept: "pattern", Weight: 0.10, UpdatedAt: now},
+					{Concept: "testing", Weight: 0.10, UpdatedAt: now},
+					{Concept: "debugging", Weight: 0.10, UpdatedAt: now},
+					{Concept: "workflow", Weight: 0.05, UpdatedAt: now},
+					{Concept: "tooling", Weight: 0.05, UpdatedAt: now},
+				}
+
+				// INSERT OR IGNORE equivalent in GORM
+				return tx.Clauses(clause.OnConflict{DoNothing: true}).Create(&weights).Error
+			},
+			Rollback: func(tx *gorm.DB) error {
+				return tx.Migrator().DropTable("concept_weights")
+			},
+		},
+
+		// Migration 008: Observation conflicts table
+		{
+			ID: "008_observation_conflicts",
+			Migrate: func(tx *gorm.DB) error {
+				return tx.AutoMigrate(&ObservationConflict{})
+			},
+			Rollback: func(tx *gorm.DB) error {
+				return tx.Migrator().DropTable("observation_conflicts")
+			},
+		},
+
+		// Migration 009: Patterns table
+		{
+			ID: "009_patterns",
+			Migrate: func(tx *gorm.DB) error {
+				return tx.AutoMigrate(&Pattern{})
+			},
+			Rollback: func(tx *gorm.DB) error {
+				return tx.Migrator().DropTable("patterns")
+			},
+		},
+
+		// Migration 010: FTS5 virtual table for patterns
+		{
+			ID: "010_patterns_fts",
+			Migrate: func(tx *gorm.DB) error {
+				sqls := []string{
+					`CREATE VIRTUAL TABLE IF NOT EXISTS patterns_fts USING fts5(
+						name, description, recommendation,
+						content='patterns',
+						content_rowid='id'
+					)`,
+					`CREATE TRIGGER IF NOT EXISTS patterns_ai AFTER INSERT ON patterns BEGIN
+						INSERT INTO patterns_fts(rowid, name, description, recommendation)
+						VALUES (new.id, new.name, new.description, new.recommendation);
+					END`,
+					`CREATE TRIGGER IF NOT EXISTS patterns_ad AFTER DELETE ON patterns BEGIN
+						INSERT INTO patterns_fts(patterns_fts, rowid, name, description, recommendation)
+						VALUES('delete', old.id, old.name, old.description, old.recommendation);
+					END`,
+					`CREATE TRIGGER IF NOT EXISTS patterns_au AFTER UPDATE ON patterns BEGIN
+						INSERT INTO patterns_fts(patterns_fts, rowid, name, description, recommendation)
+						VALUES('delete', old.id, old.name, old.description, old.recommendation);
+						INSERT INTO patterns_fts(rowid, name, description, recommendation)
+						VALUES (new.id, new.name, new.description, new.recommendation);
+					END`,
+				}
+				for _, s := range sqls {
+					if err := tx.Exec(s).Error; err != nil {
+						return err
+					}
+				}
+				return nil
+			},
+			Rollback: func(tx *gorm.DB) error {
+				sqls := []string{
+					"DROP TRIGGER IF EXISTS patterns_au",
+					"DROP TRIGGER IF EXISTS patterns_ad",
+					"DROP TRIGGER IF EXISTS patterns_ai",
+					"DROP TABLE IF EXISTS patterns_fts",
+				}
+				for _, s := range sqls {
+					if err := tx.Exec(s).Error; err != nil {
+						return err
+					}
+				}
+				return nil
+			},
+		},
+
+		// Migration 011: Observation relations table
+		{
+			ID: "011_observation_relations",
+			Migrate: func(tx *gorm.DB) error {
+				return tx.AutoMigrate(&ObservationRelation{})
+			},
+			Rollback: func(tx *gorm.DB) error {
+				return tx.Migrator().DropTable("observation_relations")
+			},
+		},
+	})
+
+	if err := m.Migrate(); err != nil {
+		return fmt.Errorf("run gormigrate migrations: %w", err)
+	}
+
+	return nil
+}

internal/db/gorm/models.go

@@ -0,0 +1,274 @@
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"database/sql"
+	"time"
+
+	"gorm.io/gorm"
+
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+)
+
+// GORM Models
+
+// Note: JSON types (JSONStringArray, JSONInt64Map) are imported from pkg/models
+// and already implement sql.Scanner and driver.Valuer interfaces.
+
+// SDKSession represents a Claude Code session.
+type SDKSession struct {
+	ID               int64          `gorm:"primaryKey;autoIncrement"`
+	ClaudeSessionID  string         `gorm:"uniqueIndex;not null"`
+	SDKSessionID     sql.NullString `gorm:"uniqueIndex"`
+	Project          string         `gorm:"index;not null"`
+	UserPrompt       sql.NullString
+	WorkerPort       sql.NullInt64
+	PromptCounter    int    `gorm:"default:0"`
+	Status           string `gorm:"type:text;check:status IN ('active', 'completed', 'failed');default:'active';index"`
+	StartedAt        string `gorm:"not null"`
+	StartedAtEpoch   int64  `gorm:"index:idx_sessions_started,sort:desc;not null"`
+	CompletedAt      sql.NullString
+	CompletedAtEpoch sql.NullInt64
+}
+
+func (SDKSession) TableName() string { return "sdk_sessions" }
+
+// BeforeCreate hook to ensure timestamps are set.
+func (s *SDKSession) BeforeCreate(tx *gorm.DB) error {
+	if s.StartedAtEpoch == 0 {
+		s.StartedAtEpoch = time.Now().UnixMilli()
+	}
+	if s.StartedAt == "" {
+		s.StartedAt = time.Now().Format(time.RFC3339)
+	}
+	return nil
+}
+
+// Observation represents a stored observation (learning).
+type Observation struct {
+	ID           int64                   `gorm:"primaryKey;autoIncrement"`
+	SDKSessionID string                  `gorm:"index;not null"`
+	Project      string                  `gorm:"index;not null"`
+	Scope        models.ObservationScope `gorm:"type:text;default:'project';check:scope IN ('project', 'global');index:idx_observations_scope;index:idx_observations_project_scope,priority:2"`
+	Type         models.ObservationType  `gorm:"type:text;check:type IN ('decision', 'bugfix', 'feature', 'refactor', 'discovery', 'change');index;not null"`
+
+	// Content fields
+	Title         sql.NullString         `gorm:"type:text"`
+	Subtitle      sql.NullString         `gorm:"type:text"`
+	Facts         models.JSONStringArray `gorm:"type:text"` // JSON array
+	Narrative     sql.NullString         `gorm:"type:text"`
+	Concepts      models.JSONStringArray `gorm:"type:text"` // JSON array
+	FilesRead     models.JSONStringArray `gorm:"type:text"` // JSON array
+	FilesModified models.JSONStringArray `gorm:"type:text"` // JSON array
+	FileMtimes    models.JSONInt64Map    `gorm:"type:text"` // JSON object
+
+	// Metadata
+	PromptNumber    sql.NullInt64
+	DiscoveryTokens int64  `gorm:"default:0"`
+	CreatedAt       string `gorm:"not null"`
+	CreatedAtEpoch  int64  `gorm:"index:idx_observations_created,sort:desc;not null"`
+
+	// Importance scoring fields
+	ImportanceScore float64       `gorm:"type:real;default:1.0;index:idx_observations_importance,priority:1,sort:desc"`
+	UserFeedback    int           `gorm:"default:0"`
+	RetrievalCount  int           `gorm:"default:0"`
+	LastRetrievedAt sql.NullInt64 `gorm:"column:last_retrieved_at_epoch"`
+	ScoreUpdatedAt  sql.NullInt64 `gorm:"column:score_updated_at_epoch;index:idx_observations_score_updated"`
+	IsSuperseded    int           `gorm:"default:0;index:idx_observations_superseded,priority:1"`
+}
+
+func (Observation) TableName() string { return "observations" }
+
+// BeforeCreate hook to ensure defaults are set.
+func (o *Observation) BeforeCreate(tx *gorm.DB) error {
+	if o.CreatedAtEpoch == 0 {
+		o.CreatedAtEpoch = time.Now().UnixMilli()
+	}
+	if o.CreatedAt == "" {
+		o.CreatedAt = time.Now().Format(time.RFC3339)
+	}
+	if o.ImportanceScore == 0 {
+		o.ImportanceScore = 1.0
+	}
+	return nil
+}
+
+// SessionSummary represents a session summary.
+type SessionSummary struct {
+	ID           int64  `gorm:"primaryKey;autoIncrement"`
+	SDKSessionID string `gorm:"index;not null"`
+	Project      string `gorm:"index;not null"`
+
+	// Summary fields (nullable TEXT)
+	Request      sql.NullString
+	Investigated sql.NullString
+	Learned      sql.NullString
+	Completed    sql.NullString
+	NextSteps    sql.NullString `gorm:"column:next_steps"`
+	Notes        sql.NullString
+
+	// Metadata
+	PromptNumber    sql.NullInt64
+	DiscoveryTokens int64  `gorm:"default:0"`
+	CreatedAt       string `gorm:"not null"`
+	CreatedAtEpoch  int64  `gorm:"index:idx_summaries_created,sort:desc;not null"`
+}
+
+func (SessionSummary) TableName() string { return "session_summaries" }
+
+// BeforeCreate hook to ensure timestamps are set.
+func (s *SessionSummary) BeforeCreate(tx *gorm.DB) error {
+	if s.CreatedAtEpoch == 0 {
+		s.CreatedAtEpoch = time.Now().UnixMilli()
+	}
+	if s.CreatedAt == "" {
+		s.CreatedAt = time.Now().Format(time.RFC3339)
+	}
+	return nil
+}
+
+// UserPrompt represents a user prompt.
+type UserPrompt struct {
+	ID                  int64  `gorm:"primaryKey;autoIncrement"`
+	ClaudeSessionID     string `gorm:"index;not null;uniqueIndex:idx_user_prompts_session_number_unique,priority:1"`
+	PromptNumber        int    `gorm:"index;not null;uniqueIndex:idx_user_prompts_session_number_unique,priority:2"`
+	PromptText          string `gorm:"type:text;not null"`
+	MatchedObservations int    `gorm:"default:0"`
+	CreatedAt           string `gorm:"not null"`
+	CreatedAtEpoch      int64  `gorm:"index:idx_prompts_created,sort:desc;not null"`
+}
+
+func (UserPrompt) TableName() string { return "user_prompts" }
+
+// BeforeCreate hook to ensure timestamps are set.
+func (p *UserPrompt) BeforeCreate(tx *gorm.DB) error {
+	if p.CreatedAtEpoch == 0 {
+		p.CreatedAtEpoch = time.Now().UnixMilli()
+	}
+	if p.CreatedAt == "" {
+		p.CreatedAt = time.Now().Format(time.RFC3339)
+	}
+	return nil
+}
+
+// ObservationConflict tracks conflicts between observations.
+type ObservationConflict struct {
+	ID              int64                     `gorm:"primaryKey;autoIncrement"`
+	NewerObsID      int64                     `gorm:"index:idx_conflicts_newer;not null"`
+	OlderObsID      int64                     `gorm:"index:idx_conflicts_older;not null"`
+	ConflictType    models.ConflictType       `gorm:"type:text;check:conflict_type IN ('superseded', 'contradicts', 'outdated_pattern');not null"`
+	Resolution      models.ConflictResolution `gorm:"type:text;check:resolution IN ('prefer_newer', 'prefer_older', 'manual');not null"`
+	Reason          sql.NullString            `gorm:"type:text"`
+	DetectedAt      string                    `gorm:"not null"`
+	DetectedAtEpoch int64                     `gorm:"index:idx_conflicts_unresolved,priority:2,sort:desc;not null"`
+	Resolved        int                       `gorm:"default:0;index:idx_conflicts_unresolved,priority:1"`
+	ResolvedAt      sql.NullString
+}
+
+func (ObservationConflict) TableName() string { return "observation_conflicts" }
+
+// BeforeCreate hook to ensure timestamps are set.
+func (c *ObservationConflict) BeforeCreate(tx *gorm.DB) error {
+	if c.DetectedAtEpoch == 0 {
+		c.DetectedAtEpoch = time.Now().UnixMilli()
+	}
+	if c.DetectedAt == "" {
+		c.DetectedAt = time.Now().Format(time.RFC3339)
+	}
+	return nil
+}
+
+// ObservationRelation tracks relationships between observations.
+type ObservationRelation struct {
+	ID              int64                          `gorm:"primaryKey;autoIncrement"`
+	SourceID        int64                          `gorm:"index:idx_relations_source;index:idx_relations_both,priority:1;uniqueIndex:idx_relations_unique,priority:1;not null"`
+	TargetID        int64                          `gorm:"index:idx_relations_target;index:idx_relations_both,priority:2;uniqueIndex:idx_relations_unique,priority:2;not null"`
+	RelationType    models.RelationType            `gorm:"type:text;check:relation_type IN ('causes', 'fixes', 'supersedes', 'depends_on', 'relates_to', 'evolves_from');index:idx_relations_type;uniqueIndex:idx_relations_unique,priority:3;not null"`
+	Confidence      float64                        `gorm:"type:real;default:0.5;index:idx_relations_confidence,sort:desc;not null"`
+	DetectionSource models.RelationDetectionSource `gorm:"type:text;check:detection_source IN ('file_overlap', 'embedding_similarity', 'temporal_proximity', 'narrative_mention', 'concept_overlap', 'type_progression');not null"`
+	Reason          sql.NullString                 `gorm:"type:text"`
+	CreatedAt       string                         `gorm:"not null"`
+	CreatedAtEpoch  int64                          `gorm:"not null"`
+}
+
+func (ObservationRelation) TableName() string { return "observation_relations" }
+
+// BeforeCreate hook to ensure timestamps are set.
+func (r *ObservationRelation) BeforeCreate(tx *gorm.DB) error {
+	if r.CreatedAtEpoch == 0 {
+		r.CreatedAtEpoch = time.Now().UnixMilli()
+	}
+	if r.CreatedAt == "" {
+		r.CreatedAt = time.Now().Format(time.RFC3339)
+	}
+	if r.Confidence == 0 {
+		r.Confidence = 0.5
+	}
+	return nil
+}
+
+// Pattern represents a detected recurring pattern.
+type Pattern struct {
+	ID              int64                  `gorm:"primaryKey;autoIncrement"`
+	Name            string                 `gorm:"type:text;not null"`
+	Type            models.PatternType     `gorm:"type:text;check:type IN ('bug', 'refactor', 'architecture', 'anti-pattern', 'best-practice');index;not null"`
+	Description     sql.NullString         `gorm:"type:text"`
+	Signature       models.JSONStringArray `gorm:"type:text"` // JSON array of keywords
+	Recommendation  sql.NullString         `gorm:"type:text"`
+	Frequency       int                    `gorm:"default:1;index:idx_patterns_frequency,sort:desc"`
+	Projects        models.JSONStringArray `gorm:"type:text"` // JSON array
+	ObservationIDs  models.JSONInt64Array  `gorm:"type:text"` // JSON array
+	Status          models.PatternStatus   `gorm:"type:text;default:'active';check:status IN ('active', 'deprecated', 'merged');index"`
+	MergedIntoID    sql.NullInt64
+	Confidence      float64 `gorm:"type:real;default:0.5;index:idx_patterns_confidence,sort:desc"`
+	LastSeenAt      string  `gorm:"not null"`
+	LastSeenAtEpoch int64   `gorm:"index:idx_patterns_last_seen,sort:desc;not null"`
+	CreatedAt       string  `gorm:"not null"`
+	CreatedAtEpoch  int64   `gorm:"not null"`
+}
+
+func (Pattern) TableName() string { return "patterns" }
+
+// BeforeCreate hook to ensure timestamps and defaults are set.
+func (p *Pattern) BeforeCreate(tx *gorm.DB) error {
+	now := time.Now()
+	if p.CreatedAtEpoch == 0 {
+		p.CreatedAtEpoch = now.UnixMilli()
+	}
+	if p.CreatedAt == "" {
+		p.CreatedAt = now.Format(time.RFC3339)
+	}
+	if p.LastSeenAtEpoch == 0 {
+		p.LastSeenAtEpoch = now.UnixMilli()
+	}
+	if p.LastSeenAt == "" {
+		p.LastSeenAt = now.Format(time.RFC3339)
+	}
+	if p.Confidence == 0 {
+		p.Confidence = 0.5
+	}
+	if p.Frequency == 0 {
+		p.Frequency = 1
+	}
+	return nil
+}
+
+// ConceptWeight stores configurable weights for importance scoring.
+type ConceptWeight struct {
+	Concept   string  `gorm:"primaryKey;type:text"`
+	Weight    float64 `gorm:"type:real;not null;default:0.1"`
+	UpdatedAt string  `gorm:"not null"`
+}
+
+func (ConceptWeight) TableName() string { return "concept_weights" }
+
+// BeforeCreate hook to ensure timestamp is set.
+func (c *ConceptWeight) BeforeCreate(tx *gorm.DB) error {
+	if c.UpdatedAt == "" {
+		c.UpdatedAt = time.Now().Format(time.RFC3339)
+	}
+	if c.Weight == 0 {
+		c.Weight = 0.1
+	}
+	return nil
+}

internal/db/gorm/observation_store.go

@@ -0,0 +1,563 @@
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+)
+
+// MaxObservationsPerProject is the maximum number of observations to keep per project.
+const MaxObservationsPerProject = 100
+
+// CleanupFunc is a callback for when observations are cleaned up.
+// Receives the IDs of deleted observations for downstream cleanup (e.g., vector DB).
+type CleanupFunc func(ctx context.Context, deletedIDs []int64)
+
+// ObservationStore provides observation-related database operations using GORM.
+type ObservationStore struct {
+	db            *gorm.DB
+	rawDB         *sql.DB
+	cleanupFunc   CleanupFunc
+	conflictStore interface{} // Placeholder for ConflictStore (Phase 4)
+	relationStore interface{} // Placeholder for RelationStore (Phase 4)
+}
+
+// NewObservationStore creates a new observation store.
+// The conflictStore and relationStore parameters are optional (can be nil) and will be used in Phase 4.
+func NewObservationStore(store *Store, cleanupFunc CleanupFunc, conflictStore, relationStore interface{}) *ObservationStore {
+	return &ObservationStore{
+		db:            store.DB,
+		rawDB:         store.GetRawDB(),
+		cleanupFunc:   cleanupFunc,
+		conflictStore: conflictStore,
+		relationStore: relationStore,
+	}
+}
+
+// SetCleanupFunc sets the callback for when observations are deleted during cleanup.
+func (s *ObservationStore) SetCleanupFunc(fn CleanupFunc) {
+	s.cleanupFunc = fn
+}
+
+// StoreObservation stores a new observation.
+func (s *ObservationStore) StoreObservation(ctx context.Context, sdkSessionID, project string, obs *models.ParsedObservation, promptNumber int, discoveryTokens int64) (int64, int64, error) {
+	now := time.Now()
+	nowEpoch := now.UnixMilli()
+
+	// Ensure session exists (auto-create if missing)
+	if err := EnsureSessionExists(ctx, s.db, sdkSessionID, project); err != nil {
+		return 0, 0, err
+	}
+
+	// Determine scope: use parsed scope if set, otherwise auto-determine from concepts
+	scope := obs.Scope
+	if scope == "" {
+		scope = models.DetermineScope(obs.Concepts)
+	}
+
+	dbObs := &Observation{
+		SDKSessionID:    sdkSessionID,
+		Project:         project,
+		Scope:           scope,
+		Type:            obs.Type,
+		Title:           nullString(obs.Title),
+		Subtitle:        nullString(obs.Subtitle),
+		Facts:           models.JSONStringArray(obs.Facts),
+		Narrative:       nullString(obs.Narrative),
+		Concepts:        models.JSONStringArray(obs.Concepts),
+		FilesRead:       models.JSONStringArray(obs.FilesRead),
+		FilesModified:   models.JSONStringArray(obs.FilesModified),
+		FileMtimes:      models.JSONInt64Map(obs.FileMtimes),
+		PromptNumber:    nullInt64(promptNumber),
+		DiscoveryTokens: discoveryTokens,
+		CreatedAt:       now.Format(time.RFC3339),
+		CreatedAtEpoch:  nowEpoch,
+	}
+
+	err := s.db.WithContext(ctx).Create(dbObs).Error
+	if err != nil {
+		return 0, 0, err
+	}
+
+	// Cleanup old observations beyond the limit for this project (async to not block handler)
+	if project != "" {
+		go func(proj string) {
+			cleanupCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+			defer cancel()
+			deletedIDs, _ := s.CleanupOldObservations(cleanupCtx, proj)
+			if len(deletedIDs) > 0 && s.cleanupFunc != nil {
+				s.cleanupFunc(cleanupCtx, deletedIDs)
+			}
+		}(project)
+	}
+
+	// Note: Conflict and relation detection intentionally omitted for now
+	// Will be added in Phase 4 when ConflictStore and RelationStore are implemented
+
+	return dbObs.ID, nowEpoch, nil
+}
+
+// GetObservationByID retrieves an observation by its ID.
+func (s *ObservationStore) GetObservationByID(ctx context.Context, id int64) (*models.Observation, error) {
+	var dbObs Observation
+	err := s.db.WithContext(ctx).First(&dbObs, id).Error
+	if err == gorm.ErrRecordNotFound {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return toModelObservation(&dbObs), nil
+}
+
+// GetObservationsByIDs retrieves observations by a list of IDs.
+func (s *ObservationStore) GetObservationsByIDs(ctx context.Context, ids []int64, orderBy string, limit int) ([]*models.Observation, error) {
+	if len(ids) == 0 {
+		return nil, nil
+	}
+
+	var dbObservations []Observation
+	query := s.db.WithContext(ctx).Where("id IN ?", ids)
+
+	// Apply ordering
+	switch orderBy {
+	case "date_asc":
+		query = query.Order("created_at_epoch ASC")
+	case "date_desc":
+		query = query.Order("created_at_epoch DESC")
+	case "importance":
+		query = query.Order("importance_score DESC, created_at_epoch DESC")
+	default:
+		// Default: importance first, then recency
+		query = query.Order("COALESCE(importance_score, 1.0) DESC, created_at_epoch DESC")
+	}
+
+	// Apply limit
+	if limit > 0 {
+		query = query.Limit(limit)
+	}
+
+	err := query.Find(&dbObservations).Error
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelObservations(dbObservations), nil
+}
+
+// GetRecentObservations retrieves recent observations for a project.
+// This includes project-scoped observations for the specified project AND global observations.
+// Results are ordered by importance_score DESC, then created_at_epoch DESC.
+func (s *ObservationStore) GetRecentObservations(ctx context.Context, project string, limit int) ([]*models.Observation, error) {
+	var dbObservations []Observation
+	err := s.db.WithContext(ctx).
+		Scopes(projectScopeFilter(project), importanceOrdering()).
+		Limit(limit).
+		Find(&dbObservations).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelObservations(dbObservations), nil
+}
+
+// GetActiveObservations retrieves recent non-superseded observations for a project.
+// This excludes observations that have been marked as superseded by newer ones.
+// Results are ordered by importance_score DESC, then created_at_epoch DESC.
+func (s *ObservationStore) GetActiveObservations(ctx context.Context, project string, limit int) ([]*models.Observation, error) {
+	var dbObservations []Observation
+	err := s.db.WithContext(ctx).
+		Scopes(projectScopeFilter(project), notSupersededFilter(), importanceOrdering()).
+		Limit(limit).
+		Find(&dbObservations).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelObservations(dbObservations), nil
+}
+
+// GetSupersededObservations retrieves observations that have been superseded by newer ones.
+// Results are ordered by created_at_epoch DESC.
+func (s *ObservationStore) GetSupersededObservations(ctx context.Context, project string, limit int) ([]*models.Observation, error) {
+	var dbObservations []Observation
+	err := s.db.WithContext(ctx).
+		Where("project = ? AND COALESCE(is_superseded, 0) = 1", project).
+		Order("created_at_epoch DESC").
+		Limit(limit).
+		Find(&dbObservations).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelObservations(dbObservations), nil
+}
+
+// GetObservationsByProjectStrict retrieves observations for a project (strict - no global observations).
+func (s *ObservationStore) GetObservationsByProjectStrict(ctx context.Context, project string, limit int) ([]*models.Observation, error) {
+	var dbObservations []Observation
+	err := s.db.WithContext(ctx).
+		Where("project = ?", project).
+		Scopes(importanceOrdering()).
+		Limit(limit).
+		Find(&dbObservations).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelObservations(dbObservations), nil
+}
+
+// GetObservationCount returns the count of observations for a project.
+func (s *ObservationStore) GetObservationCount(ctx context.Context, project string) (int, error) {
+	var count int64
+	err := s.db.WithContext(ctx).
+		Model(&Observation{}).
+		Where("project = ?", project).
+		Count(&count).Error
+
+	return int(count), err
+}
+
+// GetAllRecentObservations retrieves recent observations across all projects.
+func (s *ObservationStore) GetAllRecentObservations(ctx context.Context, limit int) ([]*models.Observation, error) {
+	var dbObservations []Observation
+	err := s.db.WithContext(ctx).
+		Scopes(importanceOrdering()).
+		Limit(limit).
+		Find(&dbObservations).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelObservations(dbObservations), nil
+}
+
+// GetAllObservations retrieves all observations (for vector rebuild).
+func (s *ObservationStore) GetAllObservations(ctx context.Context) ([]*models.Observation, error) {
+	var dbObservations []Observation
+	err := s.db.WithContext(ctx).
+		Order("id").
+		Find(&dbObservations).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelObservations(dbObservations), nil
+}
+
+// SearchObservationsFTS performs full-text search on observations using FTS5.
+// Falls back to LIKE search if FTS5 fails.
+func (s *ObservationStore) SearchObservationsFTS(ctx context.Context, query, project string, limit int) ([]*models.Observation, error) {
+	if limit <= 0 {
+		limit = 10
+	}
+
+	// Extract keywords from the query
+	keywords := extractKeywords(query)
+	if len(keywords) == 0 {
+		return nil, nil
+	}
+
+	// Build FTS5 query: keyword1 OR keyword2 OR keyword3
+	ftsTerms := strings.Join(keywords, " OR ")
+
+	// Use FTS5 via raw SQL (GORM can't handle FTS5 MATCH operator)
+	ftsQuery := `
+		SELECT o.id, o.sdk_session_id, o.project, COALESCE(o.scope, 'project') as scope, o.type,
+		       o.title, o.subtitle, o.facts, o.narrative, o.concepts, o.files_read, o.files_modified,
+		       o.file_mtimes, o.prompt_number, o.discovery_tokens, o.created_at, o.created_at_epoch,
+		       COALESCE(o.importance_score, 1.0) as importance_score,
+		       COALESCE(o.user_feedback, 0) as user_feedback,
+		       COALESCE(o.retrieval_count, 0) as retrieval_count,
+		       o.last_retrieved_at_epoch, o.score_updated_at_epoch,
+		       COALESCE(o.is_superseded, 0) as is_superseded
+		FROM observations o
+		JOIN observations_fts fts ON o.id = fts.rowid
+		WHERE observations_fts MATCH ?
+		  AND (o.project = ? OR o.scope = 'global')
+		ORDER BY rank, COALESCE(o.importance_score, 1.0) DESC
+		LIMIT ?
+	`
+
+	rows, err := s.rawDB.QueryContext(ctx, ftsQuery, ftsTerms, project, limit)
+	if err != nil {
+		// FTS failed, try LIKE fallback
+		return s.searchObservationsLike(ctx, keywords, project, limit)
+	}
+	defer rows.Close()
+
+	observations, err := scanObservationRows(rows)
+	if err != nil {
+		return nil, err
+	}
+
+	// If FTS returned nothing, try LIKE search
+	if len(observations) == 0 {
+		return s.searchObservationsLike(ctx, keywords, project, limit)
+	}
+
+	return observations, nil
+}
+
+// searchObservationsLike performs fallback LIKE search on observations using GORM.
+func (s *ObservationStore) searchObservationsLike(ctx context.Context, keywords []string, project string, limit int) ([]*models.Observation, error) {
+	if len(keywords) == 0 {
+		return nil, nil
+	}
+
+	// Build LIKE conditions for each keyword
+	var conditions []string
+	var args []interface{}
+
+	for _, kw := range keywords {
+		pattern := "%" + kw + "%"
+		conditions = append(conditions, "(title LIKE ? OR subtitle LIKE ? OR narrative LIKE ?)")
+		args = append(args, pattern, pattern, pattern)
+	}
+
+	// Build WHERE clause
+	whereClause := strings.Join(conditions, " OR ")
+	fullWhere := "(" + whereClause + ") AND (project = ? OR scope = 'global')"
+	args = append(args, project)
+
+	var dbObservations []Observation
+	err := s.db.WithContext(ctx).
+		Where(fullWhere, args...).
+		Scopes(importanceOrdering()).
+		Limit(limit).
+		Find(&dbObservations).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelObservations(dbObservations), nil
+}
+
+// DeleteObservations deletes observations by IDs.
+func (s *ObservationStore) DeleteObservations(ctx context.Context, ids []int64) (int64, error) {
+	if len(ids) == 0 {
+		return 0, nil
+	}
+
+	result := s.db.WithContext(ctx).Delete(&Observation{}, ids)
+	return result.RowsAffected, result.Error
+}
+
+// CleanupOldObservations removes observations beyond the limit for a project.
+// Returns the IDs of deleted observations.
+func (s *ObservationStore) CleanupOldObservations(ctx context.Context, project string) ([]int64, error) {
+	// Use a transaction to prevent TOCTOU race condition
+	var idsToDelete []int64
+
+	err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		// Find IDs to keep (most recent MaxObservationsPerProject)
+		var idsToKeep []int64
+		err := tx.Model(&Observation{}).
+			Where("project = ?", project).
+			Order("created_at_epoch DESC").
+			Limit(MaxObservationsPerProject).
+			Pluck("id", &idsToKeep).Error
+
+		if err != nil {
+			return err
+		}
+
+		if len(idsToKeep) == 0 {
+			return nil
+		}
+
+		// Find IDs to delete (all IDs not in the keep list)
+		// This happens in the same transaction to prevent race conditions
+		err = tx.Model(&Observation{}).
+			Where("project = ? AND id NOT IN ?", project, idsToKeep).
+			Pluck("id", &idsToDelete).Error
+
+		if err != nil {
+			return err
+		}
+
+		if len(idsToDelete) == 0 {
+			return nil
+		}
+
+		// Delete the observations
+		return tx.Delete(&Observation{}, idsToDelete).Error
+	})
+
+	if err != nil {
+		return nil, err
+	}
+
+	return idsToDelete, nil
+}
+
+// ====================
+// GORM Scopes (Reusable Query Filters)
+// ====================
+
+// projectScopeFilter filters observations by project scope.
+// Includes project-scoped observations for the specified project AND global observations.
+func projectScopeFilter(project string) func(*gorm.DB) *gorm.DB {
+	return func(db *gorm.DB) *gorm.DB {
+		return db.Where("(project = ? AND (scope IS NULL OR scope = 'project')) OR scope = 'global'", project)
+	}
+}
+
+// notSupersededFilter filters out superseded observations.
+func notSupersededFilter() func(*gorm.DB) *gorm.DB {
+	return func(db *gorm.DB) *gorm.DB {
+		return db.Where("COALESCE(is_superseded, 0) = 0")
+	}
+}
+
+// importanceOrdering orders by importance score DESC, then created_at_epoch DESC.
+func importanceOrdering() func(*gorm.DB) *gorm.DB {
+	return func(db *gorm.DB) *gorm.DB {
+		return db.Order("COALESCE(importance_score, 1.0) DESC, created_at_epoch DESC")
+	}
+}
+
+// ====================
+// Helper Functions
+// ====================
+
+// extractKeywords extracts keywords from a search query.
+func extractKeywords(query string) []string {
+	words := strings.Fields(strings.ToLower(query))
+	var keywords []string
+
+	commonWords := map[string]bool{
+		"the": true, "and": true, "or": true, "but": true, "in": true,
+		"on": true, "at": true, "to": true, "for": true, "of": true,
+		"with": true, "by": true, "from": true, "as": true, "is": true,
+		"was": true, "are": true, "were": true, "be": true, "been": true,
+		"being": true, "have": true, "has": true, "had": true, "do": true,
+		"does": true, "did": true, "will": true, "would": true, "should": true,
+		"could": true, "may": true, "might": true, "must": true, "can": true,
+	}
+
+	for _, word := range words {
+		// Skip short words and common words
+		if len(word) <= 3 || commonWords[word] {
+			continue
+		}
+		keywords = append(keywords, word)
+	}
+
+	return keywords
+}
+
+// scanObservationRows scans multiple observations from raw SQL rows.
+func scanObservationRows(rows *sql.Rows) ([]*models.Observation, error) {
+	var observations []*models.Observation
+	for rows.Next() {
+		obs, err := scanObservation(rows)
+		if err != nil {
+			return nil, err
+		}
+		observations = append(observations, obs)
+	}
+	return observations, rows.Err()
+}
+
+// scanObservation scans a single observation from a row scanner.
+func scanObservation(scanner interface{ Scan(...interface{}) error }) (*models.Observation, error) {
+	var obs models.Observation
+	var factsJSON, conceptsJSON, filesReadJSON, filesModifiedJSON, fileMtimesJSON []byte
+	var isSuperseded int
+
+	err := scanner.Scan(
+		&obs.ID, &obs.SDKSessionID, &obs.Project, &obs.Scope, &obs.Type,
+		&obs.Title, &obs.Subtitle, &factsJSON, &obs.Narrative, &conceptsJSON,
+		&filesReadJSON, &filesModifiedJSON, &fileMtimesJSON,
+		&obs.PromptNumber, &obs.DiscoveryTokens, &obs.CreatedAt, &obs.CreatedAtEpoch,
+		&obs.ImportanceScore, &obs.UserFeedback, &obs.RetrievalCount,
+		&obs.LastRetrievedAt, &obs.ScoreUpdatedAt, &isSuperseded,
+	)
+	if err != nil {
+		return nil, err
+	}
+
+	// Unmarshal JSON fields (data comes from DB, should always be valid)
+	if len(factsJSON) > 0 {
+		_ = json.Unmarshal(factsJSON, &obs.Facts)
+	}
+	if len(conceptsJSON) > 0 {
+		_ = json.Unmarshal(conceptsJSON, &obs.Concepts)
+	}
+	if len(filesReadJSON) > 0 {
+		_ = json.Unmarshal(filesReadJSON, &obs.FilesRead)
+	}
+	if len(filesModifiedJSON) > 0 {
+		_ = json.Unmarshal(filesModifiedJSON, &obs.FilesModified)
+	}
+	if len(fileMtimesJSON) > 0 {
+		_ = json.Unmarshal(fileMtimesJSON, &obs.FileMtimes)
+	}
+
+	// Convert int to bool for IsSuperseded
+	obs.IsSuperseded = isSuperseded != 0
+
+	return &obs, nil
+}
+
+// toModelObservation converts a GORM Observation to pkg/models.Observation.
+func toModelObservation(o *Observation) *models.Observation {
+	return &models.Observation{
+		ID:              o.ID,
+		SDKSessionID:    o.SDKSessionID,
+		Project:         o.Project,
+		Scope:           o.Scope,
+		Type:            o.Type,
+		Title:           o.Title,
+		Subtitle:        o.Subtitle,
+		Facts:           o.Facts,
+		Narrative:       o.Narrative,
+		Concepts:        o.Concepts,
+		FilesRead:       o.FilesRead,
+		FilesModified:   o.FilesModified,
+		FileMtimes:      o.FileMtimes,
+		PromptNumber:    o.PromptNumber,
+		DiscoveryTokens: o.DiscoveryTokens,
+		CreatedAt:       o.CreatedAt,
+		CreatedAtEpoch:  o.CreatedAtEpoch,
+		ImportanceScore: o.ImportanceScore,
+		UserFeedback:    o.UserFeedback,
+		RetrievalCount:  o.RetrievalCount,
+		LastRetrievedAt: o.LastRetrievedAt,
+		ScoreUpdatedAt:  o.ScoreUpdatedAt,
+		IsSuperseded:    o.IsSuperseded != 0, // Convert int to bool
+	}
+}
+
+// toModelObservations converts a slice of GORM Observation to pkg/models.Observation.
+func toModelObservations(observations []Observation) []*models.Observation {
+	result := make([]*models.Observation, len(observations))
+	for i := range observations {
+		result[i] = toModelObservation(&observations[i])
+	}
+	return result
+}
+
+// nullInt64 converts an int to sql.NullInt64.
+func nullInt64(val int) sql.NullInt64 {
+	if val == 0 {
+		return sql.NullInt64{Valid: false}
+	}
+	return sql.NullInt64{Int64: int64(val), Valid: true}
+}

internal/db/gorm/observation_store_test.go

@@ -0,0 +1,593 @@
+//go:build fts5
+
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm/logger"
+
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+)
+
+// testObservationStore creates an ObservationStore with a temporary database for testing.
+func testObservationStore(t *testing.T) (*ObservationStore, *Store, func()) {
+	t.Helper()
+
+	tmpDir, err := os.MkdirTemp("", "gorm_observation_test_*")
+	if err != nil {
+		t.Fatalf("create temp dir: %v", err)
+	}
+
+	dbPath := filepath.Join(tmpDir, "test.db")
+	cfg := Config{
+		Path:     dbPath,
+		MaxConns: 4,
+		LogLevel: logger.Silent,
+	}
+
+	store, err := NewStore(cfg)
+	if err != nil {
+		os.RemoveAll(tmpDir)
+		t.Fatalf("NewStore failed: %v", err)
+	}
+
+	observationStore := NewObservationStore(store, nil, nil, nil)
+
+	cleanup := func() {
+		store.Close()
+		os.RemoveAll(tmpDir)
+	}
+
+	return observationStore, store, cleanup
+}
+
+func TestObservationStore_StoreObservation(t *testing.T) {
+	observationStore, store, cleanup := testObservationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create a session first
+	sessionStore := NewSessionStore(store)
+	_, err := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+	require.NoError(t, err)
+
+	// Store an observation
+	observation := &models.ParsedObservation{
+		Type:      models.ObsTypeDecision,
+		Title:     "User prefers tabs over spaces",
+		Narrative: "Observed in code formatting",
+		Concepts:  []string{"coding-style", "preferences"},
+	}
+
+	id, epoch, err := observationStore.StoreObservation(ctx, "claude-1", "test-project", observation, 1, 100)
+	require.NoError(t, err)
+	assert.Greater(t, id, int64(0))
+	assert.Greater(t, epoch, int64(0))
+}
+
+func TestObservationStore_StoreObservation_AutoCreateSession(t *testing.T) {
+	observationStore, _, cleanup := testObservationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Store observation without pre-creating session
+	observation := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "Test auto-create",
+	}
+
+	id, _, err := observationStore.StoreObservation(ctx, "claude-auto", "auto-project", observation, 1, 50)
+	require.NoError(t, err)
+	assert.Greater(t, id, int64(0))
+}
+
+func TestObservationStore_StoreObservation_WithScope(t *testing.T) {
+	observationStore, _, cleanup := testObservationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	tests := []struct {
+		name          string
+		tags          []string
+		expectedScope models.ObservationScope
+	}{
+		{
+			name:          "Global scope - best practice",
+			tags:          []string{"best-practice", "testing"},
+			expectedScope: models.ScopeGlobal,
+		},
+		{
+			name:          "Global scope - security",
+			tags:          []string{"security", "auth"},
+			expectedScope: models.ScopeGlobal,
+		},
+		{
+			name:          "Project scope - specific feature",
+			tags:          []string{"feature", "implementation"},
+			expectedScope: models.ScopeProject,
+		},
+		{
+			name:          "Project scope - no tags",
+			tags:          []string{},
+			expectedScope: models.ScopeProject,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			observation := &models.ParsedObservation{
+				Type:     models.ObsTypeDiscovery,
+				Title:    "Test scope determination",
+				Concepts: tt.tags,
+			}
+
+			id, _, err := observationStore.StoreObservation(ctx, "claude-1", "test-project", observation, 1, 50)
+			require.NoError(t, err)
+
+			// Verify scope was set correctly
+			observations, err := observationStore.GetObservationsByIDs(ctx, []int64{id}, "default", 10)
+			require.NoError(t, err)
+			require.Len(t, observations, 1)
+			assert.Equal(t, tt.expectedScope, observations[0].Scope)
+		})
+	}
+}
+
+func TestObservationStore_StoreObservation_AsyncCleanup(t *testing.T) {
+	observationStore, _, cleanup := testObservationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Track cleanup calls
+	var cleanupMutex sync.Mutex
+	cleanupCalled := false
+	var cleanupIDs []int64
+
+	cleanupFunc := func(ctx context.Context, deletedIDs []int64) {
+		cleanupMutex.Lock()
+		defer cleanupMutex.Unlock()
+		cleanupCalled = true
+		cleanupIDs = deletedIDs
+	}
+
+	observationStore.cleanupFunc = cleanupFunc
+
+	// Store observations beyond the limit (MaxObservationsPerProject = 100)
+	for i := 0; i < 105; i++ {
+		observation := &models.ParsedObservation{
+			Type:  models.ObsTypeDiscovery,
+			Title: "Observation",
+		}
+		_, _, err := observationStore.StoreObservation(ctx, "claude-1", "test-project", observation, i, 50)
+		require.NoError(t, err)
+	}
+
+	// Wait for async cleanup to complete
+	time.Sleep(200 * time.Millisecond)
+
+	// Verify cleanup was called
+	cleanupMutex.Lock()
+	defer cleanupMutex.Unlock()
+	assert.True(t, cleanupCalled, "Cleanup function should have been called")
+	assert.NotEmpty(t, cleanupIDs, "Cleanup should have deleted some observations")
+}
+
+func TestObservationStore_GetObservationsByIDs(t *testing.T) {
+	observationStore, _, cleanup := testObservationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Store multiple observations with different importance scores
+	var ids []int64
+	for i := 1; i <= 3; i++ {
+		observation := &models.ParsedObservation{
+			Type:  models.ObsTypeDiscovery,
+			Title: "Test",
+		}
+		id, _, err := observationStore.StoreObservation(ctx, "claude-1", "test-project", observation, i, 10)
+		require.NoError(t, err)
+		ids = append(ids, id)
+
+		// Update importance score directly
+		observationStore.db.Model(&Observation{}).Where("id = ?", id).Update("importance_score", float64(i))
+		time.Sleep(10 * time.Millisecond) // Ensure different timestamps
+	}
+
+	tests := []struct {
+		name     string
+		orderBy  string
+		expected []int64
+	}{
+		{
+			name:     "Default ordering - importance desc",
+			orderBy:  "default",
+			expected: []int64{ids[2], ids[1], ids[0]}, // High to low importance
+		},
+		{
+			name:     "Importance ordering",
+			orderBy:  "importance",
+			expected: []int64{ids[2], ids[1], ids[0]},
+		},
+		{
+			name:     "Date ascending",
+			orderBy:  "date_asc",
+			expected: []int64{ids[0], ids[1], ids[2]}, // Oldest to newest
+		},
+		{
+			name:     "Date descending",
+			orderBy:  "date_desc",
+			expected: []int64{ids[2], ids[1], ids[0]}, // Newest to oldest
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			observations, err := observationStore.GetObservationsByIDs(ctx, ids, tt.orderBy, 10)
+			require.NoError(t, err)
+			require.Len(t, observations, 3)
+
+			// Verify ordering
+			for i, obs := range observations {
+				assert.Equal(t, tt.expected[i], obs.ID, "Position %d should have ID %d", i, tt.expected[i])
+			}
+		})
+	}
+}
+
+func TestObservationStore_GetObservationsByIDs_Limit(t *testing.T) {
+	observationStore, _, cleanup := testObservationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Store multiple observations
+	var ids []int64
+	for i := 1; i <= 5; i++ {
+		observation := &models.ParsedObservation{
+			Type:  models.ObsTypeDiscovery,
+			Title: "Test",
+		}
+		id, _, err := observationStore.StoreObservation(ctx, "claude-1", "test-project", observation, i, 10)
+		require.NoError(t, err)
+		ids = append(ids, id)
+	}
+
+	// Get with limit
+	observations, err := observationStore.GetObservationsByIDs(ctx, ids, "default", 3)
+	require.NoError(t, err)
+	assert.Len(t, observations, 3)
+}
+
+func TestObservationStore_GetObservationsByIDs_EmptyInput(t *testing.T) {
+	observationStore, _, cleanup := testObservationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Get with empty IDs
+	observations, err := observationStore.GetObservationsByIDs(ctx, []int64{}, "default", 10)
+	require.NoError(t, err)
+	assert.Nil(t, observations)
+}
+
+func TestObservationStore_GetRecentObservations(t *testing.T) {
+	observationStore, _, cleanup := testObservationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Store project-scoped observations
+	for i := 1; i <= 3; i++ {
+		observation := &models.ParsedObservation{
+			Type:  models.ObsTypeDiscovery,
+			Title: "Project A fact",
+		}
+		_, _, err := observationStore.StoreObservation(ctx, "claude-1", "project-a", observation, i, 10)
+		require.NoError(t, err)
+	}
+
+	// Store global-scoped observation
+	observation := &models.ParsedObservation{
+		Type:     models.ObsTypeDiscovery,
+		Title:    "Global best practice",
+		Concepts: []string{"best-practice"},
+	}
+	_, _, err := observationStore.StoreObservation(ctx, "claude-2", "project-b", observation, 1, 10)
+	require.NoError(t, err)
+
+	// Store observation for different project
+	observation = &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "Project B fact",
+	}
+	_, _, err = observationStore.StoreObservation(ctx, "claude-2", "project-b", observation, 2, 10)
+	require.NoError(t, err)
+
+	// Wait for any async cleanup to complete before querying
+	time.Sleep(100 * time.Millisecond)
+
+	// Get recent observations for project-a (should include project-a + global)
+	observations, err := observationStore.GetRecentObservations(ctx, "project-a", 10)
+	require.NoError(t, err)
+	assert.Len(t, observations, 4) // 3 project-a + 1 global
+
+	// Verify scope filtering
+	projectCount := 0
+	globalCount := 0
+	for _, obs := range observations {
+		if obs.Scope == models.ScopeProject {
+			assert.Equal(t, "project-a", obs.Project)
+			projectCount++
+		} else if obs.Scope == models.ScopeGlobal {
+			globalCount++
+		}
+	}
+	assert.Equal(t, 3, projectCount)
+	assert.Equal(t, 1, globalCount)
+}
+
+func TestObservationStore_GetActiveObservations(t *testing.T) {
+	observationStore, _, cleanup := testObservationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Store active observation
+	activeObs := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "Active observation",
+	}
+	activeID, _, err := observationStore.StoreObservation(ctx, "claude-1", "test-project", activeObs, 1, 10)
+	require.NoError(t, err)
+
+	// Store superseded observation
+	supersededObs := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "Superseded observation",
+	}
+	supersededID, _, err := observationStore.StoreObservation(ctx, "claude-1", "test-project", supersededObs, 2, 10)
+	require.NoError(t, err)
+
+	// Mark as superseded
+	observationStore.db.Model(&Observation{}).Where("id = ?", supersededID).Update("is_superseded", 1)
+
+	// Get active observations (should exclude superseded)
+	observations, err := observationStore.GetActiveObservations(ctx, "test-project", 10)
+	require.NoError(t, err)
+	assert.Len(t, observations, 1)
+	assert.Equal(t, activeID, observations[0].ID)
+	assert.False(t, observations[0].IsSuperseded)
+}
+
+func TestObservationStore_GetSupersededObservations(t *testing.T) {
+	observationStore, _, cleanup := testObservationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Store active observation
+	activeObs := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "Active observation",
+	}
+	_, _, err := observationStore.StoreObservation(ctx, "claude-1", "test-project", activeObs, 1, 10)
+	require.NoError(t, err)
+
+	// Store superseded observation
+	supersededObs := &models.ParsedObservation{
+		Type:  models.ObsTypeDiscovery,
+		Title: "Superseded observation",
+	}
+	supersededID, _, err := observationStore.StoreObservation(ctx, "claude-1", "test-project", supersededObs, 2, 10)
+	require.NoError(t, err)
+
+	// Mark as superseded
+	observationStore.db.Model(&Observation{}).Where("id = ?", supersededID).Update("is_superseded", 1)
+
+	// Get superseded observations (should exclude active)
+	observations, err := observationStore.GetSupersededObservations(ctx, "test-project", 10)
+	require.NoError(t, err)
+	assert.Len(t, observations, 1)
+	assert.Equal(t, supersededID, observations[0].ID)
+	assert.True(t, observations[0].IsSuperseded)
+}
+
+func TestObservationStore_GetObservationsByProjectStrict(t *testing.T) {
+	observationStore, _, cleanup := testObservationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Store project-scoped observations
+	for i := 1; i <= 2; i++ {
+		observation := &models.ParsedObservation{
+			Type:  models.ObsTypeDiscovery,
+			Title: "Project A fact",
+		}
+		_, _, err := observationStore.StoreObservation(ctx, "claude-1", "project-a", observation, i, 10)
+		require.NoError(t, err)
+	}
+
+	// Store global-scoped observation
+	observation := &models.ParsedObservation{
+		Type:     models.ObsTypeDiscovery,
+		Title:    "Global best practice",
+		Concepts: []string{"best-practice"},
+	}
+	_, _, err := observationStore.StoreObservation(ctx, "claude-2", "project-b", observation, 1, 10)
+	require.NoError(t, err)
+
+	// Get strict project observations (should exclude global)
+	observations, err := observationStore.GetObservationsByProjectStrict(ctx, "project-a", 10)
+	require.NoError(t, err)
+	assert.Len(t, observations, 2) // Only project-a observations
+
+	// Verify all are project-scoped
+	for _, obs := range observations {
+		assert.Equal(t, models.ScopeProject, obs.Scope)
+		assert.Equal(t, "project-a", obs.Project)
+	}
+}
+
+func TestObservationStore_SearchObservationsFTS(t *testing.T) {
+	observationStore, _, cleanup := testObservationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Store observations with searchable content
+	observations := []*models.ParsedObservation{
+		{
+			Type:     models.ObsTypeDiscovery,
+			Title:    "User prefers React for frontend development",
+			Concepts: []string{"frontend", "react"},
+		},
+		{
+			Type:     models.ObsTypeDiscovery,
+			Title:    "Backend uses Go with chi router",
+			Concepts: []string{"backend", "golang"},
+		},
+		{
+			Type:     models.ObsTypeDiscovery,
+			Title:    "Database is SQLite with FTS5",
+			Concepts: []string{"database", "sqlite"},
+		},
+	}
+
+	for i, obs := range observations {
+		_, _, err := observationStore.StoreObservation(ctx, "claude-1", "test-project", obs, i+1, 10)
+		require.NoError(t, err)
+	}
+
+	// Wait for FTS5 triggers to fire
+	time.Sleep(200 * time.Millisecond)
+
+	// Search for "React frontend"
+	results, err := observationStore.SearchObservationsFTS(ctx, "React frontend", "test-project", 10)
+	require.NoError(t, err)
+	assert.NotEmpty(t, results, "Should find observations matching 'React frontend'")
+
+	// Verify results contain relevant observation
+	found := false
+	for _, obs := range results {
+		if obs.Title.String == "User prefers React for frontend development" {
+			found = true
+			break
+		}
+	}
+	assert.True(t, found, "Should find the React observation")
+}
+
+func TestObservationStore_CleanupOldObservations(t *testing.T) {
+	observationStore, _, cleanup := testObservationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Store observations beyond the limit WITHOUT async cleanup
+	// We disable async cleanup by not setting cleanupFunc
+	var allIDs []int64
+	for i := 0; i < 105; i++ {
+		observation := &models.ParsedObservation{
+			Type:  models.ObsTypeDiscovery,
+			Title: "Observation",
+		}
+		id, _, err := observationStore.StoreObservation(ctx, "claude-1", "test-project", observation, i, 10)
+		require.NoError(t, err)
+		allIDs = append(allIDs, id)
+		time.Sleep(2 * time.Millisecond) // Ensure different timestamps
+	}
+
+	// Wait for any async cleanups to complete (even though cleanupFunc is nil)
+	time.Sleep(200 * time.Millisecond)
+
+	// Verify we have 105 observations initially (async cleanup should have run but deleted items)
+	initial, err := observationStore.GetRecentObservations(ctx, "test-project", 200)
+	require.NoError(t, err)
+
+	// If async cleanup already happened, we'll have <= 100
+	// Run cleanup manually to ensure cleanup logic works
+	deletedIDs, err := observationStore.CleanupOldObservations(ctx, "test-project")
+	require.NoError(t, err)
+
+	// After cleanup (manual or async), we should have at most 100
+	remaining, err := observationStore.GetRecentObservations(ctx, "test-project", 200)
+	require.NoError(t, err)
+	assert.LessOrEqual(t, len(remaining), 100, "Should have at most 100 observations after cleanup")
+
+	// The number deleted should match how many were over the limit
+	expectedDeleted := len(initial) - len(remaining)
+	assert.Len(t, deletedIDs, expectedDeleted, "Should delete observations beyond limit")
+}
+
+func TestObservationStore_DeleteObservations(t *testing.T) {
+	observationStore, _, cleanup := testObservationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Store multiple observations
+	var ids []int64
+	for i := 1; i <= 5; i++ {
+		observation := &models.ParsedObservation{
+			Type:  models.ObsTypeDiscovery,
+			Title: "Test",
+		}
+		id, _, err := observationStore.StoreObservation(ctx, "claude-1", "test-project", observation, i, 10)
+		require.NoError(t, err)
+		ids = append(ids, id)
+	}
+
+	// Delete first 3 observations
+	_, err := observationStore.DeleteObservations(ctx, ids[:3])
+	require.NoError(t, err)
+
+	// Verify only 2 remain
+	remaining, err := observationStore.GetRecentObservations(ctx, "test-project", 10)
+	require.NoError(t, err)
+	assert.Len(t, remaining, 2)
+
+	// Verify deleted observations are gone
+	deleted, err := observationStore.GetObservationsByIDs(ctx, ids[:3], "default", 10)
+	require.NoError(t, err)
+	assert.Empty(t, deleted)
+}
+
+// Note: TestObservationStore_MarkObservationsSuperseded is omitted because
+// MarkObservationsSuperseded is a ConflictStore method (Phase 4), not ObservationStore
+
+func TestObservationStore_GetAllObservations(t *testing.T) {
+	observationStore, _, cleanup := testObservationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Store observations across projects
+	_, _, err := observationStore.StoreObservation(ctx, "claude-1", "project-a", &models.ParsedObservation{Type: models.ObsTypeDiscovery, Title: "A1"}, 1, 10)
+	require.NoError(t, err)
+
+	_, _, err = observationStore.StoreObservation(ctx, "claude-2", "project-b", &models.ParsedObservation{Type: models.ObsTypeDiscovery, Title: "B1"}, 1, 10)
+	require.NoError(t, err)
+
+	// Get all observations (for vector rebuild)
+	all, err := observationStore.GetAllObservations(ctx)
+	require.NoError(t, err)
+	assert.Len(t, all, 2)
+
+	// Verify ordering by ID
+	assert.Less(t, all[0].ID, all[1].ID)
+}

internal/db/gorm/pattern_store.go

@@ -0,0 +1,420 @@
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"context"
+	"database/sql"
+	"time"
+
+	"gorm.io/gorm"
+
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+)
+
+// PatternCleanupFunc is a callback for when patterns are deleted.
+type PatternCleanupFunc func(ctx context.Context, deletedIDs []int64)
+
+// PatternStore provides pattern-related database operations using GORM.
+type PatternStore struct {
+	db          *gorm.DB
+	cleanupFunc PatternCleanupFunc
+}
+
+// NewPatternStore creates a new pattern store.
+func NewPatternStore(store *Store) *PatternStore {
+	return &PatternStore{
+		db: store.DB,
+	}
+}
+
+// SetCleanupFunc sets the callback for when patterns are deleted.
+func (s *PatternStore) SetCleanupFunc(fn PatternCleanupFunc) {
+	s.cleanupFunc = fn
+}
+
+// StorePattern stores a new pattern.
+func (s *PatternStore) StorePattern(ctx context.Context, pattern *models.Pattern) (int64, error) {
+	dbPattern := &Pattern{
+		Name:            pattern.Name,
+		Type:            pattern.Type,
+		Signature:       pattern.Signature,
+		Frequency:       pattern.Frequency,
+		Projects:        pattern.Projects,
+		ObservationIDs:  pattern.ObservationIDs,
+		Status:          pattern.Status,
+		Confidence:      pattern.Confidence,
+		LastSeenAt:      pattern.LastSeenAt,
+		LastSeenAtEpoch: pattern.LastSeenEpoch,
+		CreatedAt:       pattern.CreatedAt,
+		CreatedAtEpoch:  pattern.CreatedAtEpoch,
+	}
+
+	if pattern.Description.Valid {
+		dbPattern.Description = sql.NullString{String: pattern.Description.String, Valid: true}
+	}
+
+	if pattern.Recommendation.Valid {
+		dbPattern.Recommendation = sql.NullString{String: pattern.Recommendation.String, Valid: true}
+	}
+
+	if pattern.MergedIntoID.Valid {
+		dbPattern.MergedIntoID = sql.NullInt64{Int64: pattern.MergedIntoID.Int64, Valid: true}
+	}
+
+	result := s.db.WithContext(ctx).Create(dbPattern)
+	if result.Error != nil {
+		return 0, result.Error
+	}
+
+	return dbPattern.ID, nil
+}
+
+// UpdatePattern updates an existing pattern.
+func (s *PatternStore) UpdatePattern(ctx context.Context, pattern *models.Pattern) error {
+	updates := map[string]interface{}{
+		"name":               pattern.Name,
+		"type":               pattern.Type,
+		"signature":          pattern.Signature,
+		"frequency":          pattern.Frequency,
+		"projects":           pattern.Projects,
+		"observation_ids":    pattern.ObservationIDs,
+		"status":             pattern.Status,
+		"confidence":         pattern.Confidence,
+		"last_seen_at":       pattern.LastSeenAt,
+		"last_seen_at_epoch": pattern.LastSeenEpoch,
+	}
+
+	if pattern.Description.Valid {
+		updates["description"] = pattern.Description.String
+	} else {
+		updates["description"] = nil
+	}
+
+	if pattern.Recommendation.Valid {
+		updates["recommendation"] = pattern.Recommendation.String
+	} else {
+		updates["recommendation"] = nil
+	}
+
+	if pattern.MergedIntoID.Valid {
+		updates["merged_into_id"] = pattern.MergedIntoID.Int64
+	} else {
+		updates["merged_into_id"] = nil
+	}
+
+	result := s.db.WithContext(ctx).
+		Model(&Pattern{}).
+		Where("id = ?", pattern.ID).
+		Updates(updates)
+
+	return result.Error
+}
+
+// GetPatternByID retrieves a pattern by ID.
+func (s *PatternStore) GetPatternByID(ctx context.Context, id int64) (*models.Pattern, error) {
+	var dbPattern Pattern
+
+	err := s.db.WithContext(ctx).First(&dbPattern, id).Error
+	if err == gorm.ErrRecordNotFound {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelPattern(&dbPattern), nil
+}
+
+// GetPatternByName retrieves a pattern by name.
+func (s *PatternStore) GetPatternByName(ctx context.Context, name string) (*models.Pattern, error) {
+	var dbPattern Pattern
+
+	err := s.db.WithContext(ctx).
+		Where("name = ? AND status = ?", name, models.PatternStatusActive).
+		First(&dbPattern).Error
+
+	if err == gorm.ErrRecordNotFound {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelPattern(&dbPattern), nil
+}
+
+// GetActivePatterns retrieves all active patterns.
+func (s *PatternStore) GetActivePatterns(ctx context.Context, limit int) ([]*models.Pattern, error) {
+	var patterns []Pattern
+
+	err := s.db.WithContext(ctx).
+		Where("status = ?", models.PatternStatusActive).
+		Order("frequency DESC, confidence DESC").
+		Limit(limit).
+		Find(&patterns).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelPatterns(patterns), nil
+}
+
+// GetPatternsByType retrieves patterns of a specific type.
+func (s *PatternStore) GetPatternsByType(ctx context.Context, patternType models.PatternType, limit int) ([]*models.Pattern, error) {
+	var patterns []Pattern
+
+	err := s.db.WithContext(ctx).
+		Where("type = ? AND status = ?", patternType, models.PatternStatusActive).
+		Order("frequency DESC, confidence DESC").
+		Limit(limit).
+		Find(&patterns).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelPatterns(patterns), nil
+}
+
+// GetPatternsByProject retrieves patterns that have been observed in a specific project.
+// Uses raw SQL since JSON_EACH is complex in GORM.
+func (s *PatternStore) GetPatternsByProject(ctx context.Context, project string, limit int) ([]*models.Pattern, error) {
+	var patterns []Pattern
+
+	// Use raw SQL for JSON_EACH query
+	query := `
+		SELECT * FROM patterns
+		WHERE status = 'active'
+		AND EXISTS (
+			SELECT 1 FROM json_each(projects)
+			WHERE json_each.value = ?
+		)
+		ORDER BY frequency DESC, confidence DESC
+		LIMIT ?
+	`
+
+	err := s.db.WithContext(ctx).
+		Raw(query, project, limit).
+		Scan(&patterns).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelPatterns(patterns), nil
+}
+
+// FindMatchingPatterns searches for patterns that match a given signature.
+// Pattern matching is done in Go code for simplicity.
+func (s *PatternStore) FindMatchingPatterns(ctx context.Context, signature []string, minScore float64) ([]*models.Pattern, error) {
+	// Get all active patterns
+	patterns, err := s.GetActivePatterns(ctx, 100)
+	if err != nil {
+		return nil, err
+	}
+
+	// Filter by signature match in Go
+	var matches []*models.Pattern
+	for _, pattern := range patterns {
+		score := models.CalculateMatchScore(signature, pattern.Signature)
+		if score >= minScore {
+			matches = append(matches, pattern)
+		}
+	}
+
+	return matches, nil
+}
+
+// MarkPatternDeprecated marks a pattern as deprecated.
+func (s *PatternStore) MarkPatternDeprecated(ctx context.Context, id int64) error {
+	result := s.db.WithContext(ctx).
+		Model(&Pattern{}).
+		Where("id = ?", id).
+		Update("status", models.PatternStatusDeprecated)
+
+	return result.Error
+}
+
+// MergePatterns merges a source pattern into a target pattern.
+func (s *PatternStore) MergePatterns(ctx context.Context, sourceID, targetID int64) error {
+	// Get both patterns
+	source, err := s.GetPatternByID(ctx, sourceID)
+	if err != nil {
+		return err
+	}
+	target, err := s.GetPatternByID(ctx, targetID)
+	if err != nil {
+		return err
+	}
+
+	// Merge source into target
+	target.Frequency += source.Frequency
+
+	// Merge projects (deduplicate)
+	for _, proj := range source.Projects {
+		found := false
+		for _, existing := range target.Projects {
+			if existing == proj {
+				found = true
+				break
+			}
+		}
+		if !found {
+			target.Projects = append(target.Projects, proj)
+		}
+	}
+
+	// Merge observation IDs (deduplicate)
+	for _, obsID := range source.ObservationIDs {
+		found := false
+		for _, existing := range target.ObservationIDs {
+			if existing == obsID {
+				found = true
+				break
+			}
+		}
+		if !found {
+			target.ObservationIDs = append(target.ObservationIDs, obsID)
+		}
+	}
+
+	// Update target
+	if err := s.UpdatePattern(ctx, target); err != nil {
+		return err
+	}
+
+	// Mark source as merged
+	source.Status = models.PatternStatusMerged
+	source.MergedIntoID = sql.NullInt64{Int64: targetID, Valid: true}
+	return s.UpdatePattern(ctx, source)
+}
+
+// DeletePattern deletes a pattern by ID.
+func (s *PatternStore) DeletePattern(ctx context.Context, id int64) error {
+	result := s.db.WithContext(ctx).Delete(&Pattern{}, id)
+
+	if result.Error == nil && s.cleanupFunc != nil {
+		s.cleanupFunc(ctx, []int64{id})
+	}
+
+	return result.Error
+}
+
+// SearchPatternsFTS performs full-text search on patterns.
+// Uses raw SQL for FTS5 query.
+func (s *PatternStore) SearchPatternsFTS(ctx context.Context, searchQuery string, limit int) ([]*models.Pattern, error) {
+	var patterns []Pattern
+
+	// Use raw SQL for FTS5 MATCH query
+	query := `
+		SELECT p.*
+		FROM patterns p
+		JOIN patterns_fts fts ON p.id = fts.rowid
+		WHERE patterns_fts MATCH ?
+		AND p.status = 'active'
+		ORDER BY rank
+		LIMIT ?
+	`
+
+	err := s.db.WithContext(ctx).
+		Raw(query, searchQuery, limit).
+		Scan(&patterns).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelPatterns(patterns), nil
+}
+
+// PatternStats contains aggregate statistics about patterns.
+type PatternStats struct {
+	Total            int     `json:"total"`
+	Active           int     `json:"active"`
+	Deprecated       int     `json:"deprecated"`
+	Merged           int     `json:"merged"`
+	TotalOccurrences int     `json:"total_occurrences"`
+	AvgConfidence    float64 `json:"avg_confidence"`
+	Bugs             int     `json:"bugs"`
+	Refactors        int     `json:"refactors"`
+	Architectures    int     `json:"architectures"`
+	AntiPatterns     int     `json:"anti_patterns"`
+	BestPractices    int     `json:"best_practices"`
+}
+
+// GetPatternStats returns statistics about patterns.
+// Uses raw SQL for complex aggregate query.
+func (s *PatternStore) GetPatternStats(ctx context.Context) (*PatternStats, error) {
+	var stats PatternStats
+
+	query := `
+		SELECT
+			COUNT(*) as total,
+			COUNT(CASE WHEN status = 'active' THEN 1 END) as active,
+			COUNT(CASE WHEN status = 'deprecated' THEN 1 END) as deprecated,
+			COUNT(CASE WHEN status = 'merged' THEN 1 END) as merged,
+			COALESCE(SUM(frequency), 0) as total_occurrences,
+			COALESCE(AVG(confidence), 0) as avg_confidence,
+			COUNT(CASE WHEN type = 'bug' THEN 1 END) as bugs,
+			COUNT(CASE WHEN type = 'refactor' THEN 1 END) as refactors,
+			COUNT(CASE WHEN type = 'architecture' THEN 1 END) as architectures,
+			COUNT(CASE WHEN type = 'anti-pattern' THEN 1 END) as anti_patterns,
+			COUNT(CASE WHEN type = 'best-practice' THEN 1 END) as best_practices
+		FROM patterns
+	`
+
+	err := s.db.WithContext(ctx).Raw(query).Scan(&stats).Error
+	return &stats, err
+}
+
+// IncrementPatternFrequency atomically increments a pattern's frequency and updates last_seen.
+func (s *PatternStore) IncrementPatternFrequency(ctx context.Context, id int64, project string, observationID int64) error {
+	now := time.Now()
+
+	// Get current pattern
+	pattern, err := s.GetPatternByID(ctx, id)
+	if err != nil {
+		return err
+	}
+
+	// Add occurrence
+	pattern.AddOccurrence(project, observationID)
+	pattern.LastSeenAt = now.Format(time.RFC3339)
+	pattern.LastSeenEpoch = now.UnixMilli()
+
+	return s.UpdatePattern(ctx, pattern)
+}
+
+// toModelPattern converts a GORM Pattern to a pkg/models Pattern.
+func toModelPattern(p *Pattern) *models.Pattern {
+	pattern := &models.Pattern{
+		ID:             p.ID,
+		Name:           p.Name,
+		Type:           p.Type,
+		Description:    p.Description,
+		Signature:      p.Signature,
+		Recommendation: p.Recommendation,
+		Frequency:      p.Frequency,
+		Projects:       p.Projects,
+		ObservationIDs: p.ObservationIDs,
+		Status:         p.Status,
+		MergedIntoID:   p.MergedIntoID,
+		Confidence:     p.Confidence,
+		LastSeenAt:     p.LastSeenAt,
+		LastSeenEpoch:  p.LastSeenAtEpoch,
+		CreatedAt:      p.CreatedAt,
+		CreatedAtEpoch: p.CreatedAtEpoch,
+	}
+
+	return pattern
+}
+
+// toModelPatterns converts a slice of GORM Patterns to pkg/models Patterns.
+func toModelPatterns(patterns []Pattern) []*models.Pattern {
+	result := make([]*models.Pattern, len(patterns))
+	for i, p := range patterns {
+		result[i] = toModelPattern(&p)
+	}
+	return result
+}

internal/db/gorm/pattern_store_test.go

@@ -0,0 +1,485 @@
+//go:build fts5
+
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"context"
+	"database/sql"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm/logger"
+
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+)
+
+func testPatternStore(t *testing.T) (*PatternStore, *Store, func()) {
+	t.Helper()
+
+	tmpDir, err := os.MkdirTemp("", "gorm_pattern_test_*")
+	if err != nil {
+		t.Fatalf("create temp dir: %v", err)
+	}
+
+	dbPath := filepath.Join(tmpDir, "test.db")
+	cfg := Config{
+		Path:     dbPath,
+		MaxConns: 4,
+		LogLevel: logger.Silent,
+	}
+
+	store, err := NewStore(cfg)
+	if err != nil {
+		os.RemoveAll(tmpDir)
+		t.Fatalf("NewStore failed: %v", err)
+	}
+
+	patternStore := NewPatternStore(store)
+
+	cleanup := func() {
+		store.Close()
+		os.RemoveAll(tmpDir)
+	}
+
+	return patternStore, store, cleanup
+}
+
+func TestPatternStore_StorePattern(t *testing.T) {
+	patternStore, _, cleanup := testPatternStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	now := time.Now()
+	pattern := &models.Pattern{
+		Name:           "Test Pattern",
+		Type:           models.PatternTypeBug,
+		Description:    sql.NullString{String: "Test description", Valid: true},
+		Signature:      []string{"bug", "error"},
+		Recommendation: sql.NullString{String: "Fix it", Valid: true},
+		Frequency:      1,
+		Projects:       []string{"test-project"},
+		ObservationIDs: []int64{1, 2, 3},
+		Status:         models.PatternStatusActive,
+		Confidence:     0.8,
+		LastSeenAt:     now.Format(time.RFC3339),
+		LastSeenEpoch:  now.UnixMilli(),
+		CreatedAt:      now.Format(time.RFC3339),
+		CreatedAtEpoch: now.UnixMilli(),
+	}
+
+	id, err := patternStore.StorePattern(ctx, pattern)
+	require.NoError(t, err)
+	assert.Greater(t, id, int64(0))
+
+	// Verify pattern was stored
+	retrieved, err := patternStore.GetPatternByID(ctx, id)
+	require.NoError(t, err)
+	assert.Equal(t, pattern.Name, retrieved.Name)
+	assert.Equal(t, pattern.Type, retrieved.Type)
+	assert.Equal(t, pattern.Signature, retrieved.Signature)
+	assert.Equal(t, pattern.Frequency, retrieved.Frequency)
+	assert.Equal(t, pattern.Status, retrieved.Status)
+	assert.Equal(t, pattern.Confidence, retrieved.Confidence)
+}
+
+func TestPatternStore_UpdatePattern(t *testing.T) {
+	patternStore, _, cleanup := testPatternStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	now := time.Now()
+	pattern := &models.Pattern{
+		Name:           "Original",
+		Type:           models.PatternTypeBug,
+		Frequency:      1,
+		Status:         models.PatternStatusActive,
+		Confidence:     0.5,
+		LastSeenAt:     now.Format(time.RFC3339),
+		LastSeenEpoch:  now.UnixMilli(),
+		CreatedAt:      now.Format(time.RFC3339),
+		CreatedAtEpoch: now.UnixMilli(),
+	}
+
+	id, err := patternStore.StorePattern(ctx, pattern)
+	require.NoError(t, err)
+
+	// Update pattern
+	pattern.ID = id
+	pattern.Name = "Updated"
+	pattern.Frequency = 5
+	pattern.Confidence = 0.9
+
+	err = patternStore.UpdatePattern(ctx, pattern)
+	require.NoError(t, err)
+
+	// Verify update
+	retrieved, err := patternStore.GetPatternByID(ctx, id)
+	require.NoError(t, err)
+	assert.Equal(t, "Updated", retrieved.Name)
+	assert.Equal(t, 5, retrieved.Frequency)
+	assert.Equal(t, 0.9, retrieved.Confidence)
+}
+
+func TestPatternStore_GetPatternByName(t *testing.T) {
+	patternStore, _, cleanup := testPatternStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	now := time.Now()
+	pattern := &models.Pattern{
+		Name:           "Unique Pattern",
+		Type:           models.PatternTypeRefactor,
+		Frequency:      1,
+		Status:         models.PatternStatusActive,
+		Confidence:     0.7,
+		LastSeenAt:     now.Format(time.RFC3339),
+		LastSeenEpoch:  now.UnixMilli(),
+		CreatedAt:      now.Format(time.RFC3339),
+		CreatedAtEpoch: now.UnixMilli(),
+	}
+
+	_, err := patternStore.StorePattern(ctx, pattern)
+	require.NoError(t, err)
+
+	// Retrieve by name
+	retrieved, err := patternStore.GetPatternByName(ctx, "Unique Pattern")
+	require.NoError(t, err)
+	require.NotNil(t, retrieved)
+	assert.Equal(t, "Unique Pattern", retrieved.Name)
+	assert.Equal(t, models.PatternTypeRefactor, retrieved.Type)
+
+	// Non-existent pattern
+	notFound, err := patternStore.GetPatternByName(ctx, "Nonexistent")
+	require.NoError(t, err)
+	assert.Nil(t, notFound)
+}
+
+func TestPatternStore_GetActivePatterns(t *testing.T) {
+	patternStore, _, cleanup := testPatternStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	now := time.Now()
+
+	// Create active patterns
+	for i := 0; i < 3; i++ {
+		pattern := &models.Pattern{
+			Name:           "Pattern " + string(rune('A'+i)),
+			Type:           models.PatternTypeBug,
+			Frequency:      i + 1, // Different frequencies for sorting
+			Status:         models.PatternStatusActive,
+			Confidence:     0.8,
+			LastSeenAt:     now.Format(time.RFC3339),
+			LastSeenEpoch:  now.UnixMilli(),
+			CreatedAt:      now.Format(time.RFC3339),
+			CreatedAtEpoch: now.UnixMilli(),
+		}
+		_, err := patternStore.StorePattern(ctx, pattern)
+		require.NoError(t, err)
+	}
+
+	// Create deprecated pattern (should not be included)
+	deprecatedPattern := &models.Pattern{
+		Name:           "Deprecated Pattern",
+		Type:           models.PatternTypeBug,
+		Frequency:      100,
+		Status:         models.PatternStatusDeprecated,
+		Confidence:     0.9,
+		LastSeenAt:     now.Format(time.RFC3339),
+		LastSeenEpoch:  now.UnixMilli(),
+		CreatedAt:      now.Format(time.RFC3339),
+		CreatedAtEpoch: now.UnixMilli(),
+	}
+	_, err := patternStore.StorePattern(ctx, deprecatedPattern)
+	require.NoError(t, err)
+
+	// Get active patterns
+	patterns, err := patternStore.GetActivePatterns(ctx, 10)
+	require.NoError(t, err)
+	assert.Len(t, patterns, 3) // Only active patterns
+
+	// Verify sorted by frequency DESC
+	assert.Equal(t, 3, patterns[0].Frequency)
+	assert.Equal(t, 2, patterns[1].Frequency)
+	assert.Equal(t, 1, patterns[2].Frequency)
+}
+
+func TestPatternStore_GetPatternsByType(t *testing.T) {
+	patternStore, _, cleanup := testPatternStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	now := time.Now()
+
+	// Create patterns of different types
+	bugPattern := &models.Pattern{
+		Name:           "Bug Pattern",
+		Type:           models.PatternTypeBug,
+		Frequency:      1,
+		Status:         models.PatternStatusActive,
+		Confidence:     0.8,
+		LastSeenAt:     now.Format(time.RFC3339),
+		LastSeenEpoch:  now.UnixMilli(),
+		CreatedAt:      now.Format(time.RFC3339),
+		CreatedAtEpoch: now.UnixMilli(),
+	}
+	_, err := patternStore.StorePattern(ctx, bugPattern)
+	require.NoError(t, err)
+
+	refactorPattern := &models.Pattern{
+		Name:           "Refactor Pattern",
+		Type:           models.PatternTypeRefactor,
+		Frequency:      1,
+		Status:         models.PatternStatusActive,
+		Confidence:     0.7,
+		LastSeenAt:     now.Format(time.RFC3339),
+		LastSeenEpoch:  now.UnixMilli(),
+		CreatedAt:      now.Format(time.RFC3339),
+		CreatedAtEpoch: now.UnixMilli(),
+	}
+	_, err = patternStore.StorePattern(ctx, refactorPattern)
+	require.NoError(t, err)
+
+	// Get only bug patterns
+	bugPatterns, err := patternStore.GetPatternsByType(ctx, models.PatternTypeBug, 10)
+	require.NoError(t, err)
+	assert.Len(t, bugPatterns, 1)
+	assert.Equal(t, "Bug Pattern", bugPatterns[0].Name)
+	assert.Equal(t, models.PatternTypeBug, bugPatterns[0].Type)
+
+	// Get only refactor patterns
+	refactorPatterns, err := patternStore.GetPatternsByType(ctx, models.PatternTypeRefactor, 10)
+	require.NoError(t, err)
+	assert.Len(t, refactorPatterns, 1)
+	assert.Equal(t, "Refactor Pattern", refactorPatterns[0].Name)
+}
+
+func TestPatternStore_MarkPatternDeprecated(t *testing.T) {
+	patternStore, _, cleanup := testPatternStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	now := time.Now()
+	pattern := &models.Pattern{
+		Name:           "To Deprecate",
+		Type:           models.PatternTypeBug,
+		Frequency:      1,
+		Status:         models.PatternStatusActive,
+		Confidence:     0.5,
+		LastSeenAt:     now.Format(time.RFC3339),
+		LastSeenEpoch:  now.UnixMilli(),
+		CreatedAt:      now.Format(time.RFC3339),
+		CreatedAtEpoch: now.UnixMilli(),
+	}
+
+	id, err := patternStore.StorePattern(ctx, pattern)
+	require.NoError(t, err)
+
+	// Mark as deprecated
+	err = patternStore.MarkPatternDeprecated(ctx, id)
+	require.NoError(t, err)
+
+	// Verify status changed
+	retrieved, err := patternStore.GetPatternByID(ctx, id)
+	require.NoError(t, err)
+	assert.Equal(t, models.PatternStatusDeprecated, retrieved.Status)
+}
+
+func TestPatternStore_MergePatterns(t *testing.T) {
+	patternStore, _, cleanup := testPatternStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	now := time.Now()
+
+	// Create source pattern
+	source := &models.Pattern{
+		Name:           "Source Pattern",
+		Type:           models.PatternTypeBug,
+		Frequency:      5,
+		Projects:       []string{"project-a", "project-b"},
+		ObservationIDs: []int64{1, 2, 3},
+		Status:         models.PatternStatusActive,
+		Confidence:     0.7,
+		LastSeenAt:     now.Format(time.RFC3339),
+		LastSeenEpoch:  now.UnixMilli(),
+		CreatedAt:      now.Format(time.RFC3339),
+		CreatedAtEpoch: now.UnixMilli(),
+	}
+	sourceID, err := patternStore.StorePattern(ctx, source)
+	require.NoError(t, err)
+
+	// Create target pattern
+	target := &models.Pattern{
+		Name:           "Target Pattern",
+		Type:           models.PatternTypeBug,
+		Frequency:      10,
+		Projects:       []string{"project-b", "project-c"},
+		ObservationIDs: []int64{3, 4, 5},
+		Status:         models.PatternStatusActive,
+		Confidence:     0.8,
+		LastSeenAt:     now.Format(time.RFC3339),
+		LastSeenEpoch:  now.UnixMilli(),
+		CreatedAt:      now.Format(time.RFC3339),
+		CreatedAtEpoch: now.UnixMilli(),
+	}
+	targetID, err := patternStore.StorePattern(ctx, target)
+	require.NoError(t, err)
+
+	// Merge source into target
+	err = patternStore.MergePatterns(ctx, sourceID, targetID)
+	require.NoError(t, err)
+
+	// Verify target was updated
+	mergedTarget, err := patternStore.GetPatternByID(ctx, targetID)
+	require.NoError(t, err)
+	assert.Equal(t, 15, mergedTarget.Frequency) // 5 + 10
+	assert.ElementsMatch(t, []string{"project-a", "project-b", "project-c"}, mergedTarget.Projects)
+	assert.ElementsMatch(t, []int64{1, 2, 3, 4, 5}, mergedTarget.ObservationIDs)
+
+	// Verify source was marked as merged
+	mergedSource, err := patternStore.GetPatternByID(ctx, sourceID)
+	require.NoError(t, err)
+	assert.Equal(t, models.PatternStatusMerged, mergedSource.Status)
+	assert.True(t, mergedSource.MergedIntoID.Valid)
+	assert.Equal(t, targetID, mergedSource.MergedIntoID.Int64)
+}
+
+func TestPatternStore_DeletePattern(t *testing.T) {
+	patternStore, _, cleanup := testPatternStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	now := time.Now()
+	pattern := &models.Pattern{
+		Name:           "To Delete",
+		Type:           models.PatternTypeBug,
+		Frequency:      1,
+		Status:         models.PatternStatusActive,
+		Confidence:     0.5,
+		LastSeenAt:     now.Format(time.RFC3339),
+		LastSeenEpoch:  now.UnixMilli(),
+		CreatedAt:      now.Format(time.RFC3339),
+		CreatedAtEpoch: now.UnixMilli(),
+	}
+
+	id, err := patternStore.StorePattern(ctx, pattern)
+	require.NoError(t, err)
+
+	// Delete pattern
+	err = patternStore.DeletePattern(ctx, id)
+	require.NoError(t, err)
+
+	// Verify deleted
+	deleted, err := patternStore.GetPatternByID(ctx, id)
+	require.NoError(t, err)
+	assert.Nil(t, deleted)
+}
+
+func TestPatternStore_IncrementPatternFrequency(t *testing.T) {
+	patternStore, _, cleanup := testPatternStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	now := time.Now()
+	pattern := &models.Pattern{
+		Name:           "Frequency Test",
+		Type:           models.PatternTypeBug,
+		Frequency:      1,
+		Projects:       []string{"project-a"},
+		ObservationIDs: []int64{},
+		Status:         models.PatternStatusActive,
+		Confidence:     0.7,
+		LastSeenAt:     now.Format(time.RFC3339),
+		LastSeenEpoch:  now.UnixMilli(),
+		CreatedAt:      now.Format(time.RFC3339),
+		CreatedAtEpoch: now.UnixMilli(),
+	}
+
+	id, err := patternStore.StorePattern(ctx, pattern)
+	require.NoError(t, err)
+
+	// Increment frequency with new project and observation
+	err = patternStore.IncrementPatternFrequency(ctx, id, "project-b", 42)
+	require.NoError(t, err)
+
+	// Verify frequency incremented and new data added
+	updated, err := patternStore.GetPatternByID(ctx, id)
+	require.NoError(t, err)
+	assert.Equal(t, 2, updated.Frequency)
+	assert.ElementsMatch(t, []string{"project-a", "project-b"}, updated.Projects)
+	assert.Contains(t, updated.ObservationIDs, int64(42))
+
+	// Last seen should be updated (rough check - within last 5 seconds)
+	updatedTime, _ := time.Parse(time.RFC3339, updated.LastSeenAt)
+	assert.WithinDuration(t, time.Now(), updatedTime, 5*time.Second)
+}
+
+func TestPatternStore_GetPatternStats(t *testing.T) {
+	patternStore, _, cleanup := testPatternStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	now := time.Now()
+
+	// Create patterns with different statuses and types
+	patterns := []*models.Pattern{
+		{
+			Name:           "Bug 1",
+			Type:           models.PatternTypeBug,
+			Frequency:      10,
+			Status:         models.PatternStatusActive,
+			Confidence:     0.8,
+			LastSeenAt:     now.Format(time.RFC3339),
+			LastSeenEpoch:  now.UnixMilli(),
+			CreatedAt:      now.Format(time.RFC3339),
+			CreatedAtEpoch: now.UnixMilli(),
+		},
+		{
+			Name:           "Refactor 1",
+			Type:           models.PatternTypeRefactor,
+			Frequency:      5,
+			Status:         models.PatternStatusActive,
+			Confidence:     0.7,
+			LastSeenAt:     now.Format(time.RFC3339),
+			LastSeenEpoch:  now.UnixMilli(),
+			CreatedAt:      now.Format(time.RFC3339),
+			CreatedAtEpoch: now.UnixMilli(),
+		},
+		{
+			Name:           "Deprecated 1",
+			Type:           models.PatternTypeBestPractice,
+			Frequency:      3,
+			Status:         models.PatternStatusDeprecated,
+			Confidence:     0.6,
+			LastSeenAt:     now.Format(time.RFC3339),
+			LastSeenEpoch:  now.UnixMilli(),
+			CreatedAt:      now.Format(time.RFC3339),
+			CreatedAtEpoch: now.UnixMilli(),
+		},
+	}
+
+	for _, p := range patterns {
+		_, err := patternStore.StorePattern(ctx, p)
+		require.NoError(t, err)
+	}
+
+	// Get stats
+	stats, err := patternStore.GetPatternStats(ctx)
+	require.NoError(t, err)
+
+	assert.Equal(t, 3, stats.Total)
+	assert.Equal(t, 2, stats.Active)
+	assert.Equal(t, 1, stats.Deprecated)
+	assert.Equal(t, 0, stats.Merged)
+	assert.Equal(t, 18, stats.TotalOccurrences)       // 10 + 5 + 3
+	assert.InDelta(t, 0.7, stats.AvgConfidence, 0.05) // (0.8 + 0.7 + 0.6) / 3
+	assert.Equal(t, 1, stats.Bugs)
+	assert.Equal(t, 1, stats.Refactors)
+	assert.Equal(t, 1, stats.BestPractices)
+}

internal/db/gorm/prompt_store.go

@@ -0,0 +1,317 @@
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"context"
+	"database/sql"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+)
+
+// PromptCleanupFunc is a callback for when prompts are cleaned up.
+// Receives the IDs of deleted prompts for downstream cleanup (e.g., vector DB).
+type PromptCleanupFunc func(ctx context.Context, deletedIDs []int64)
+
+// MaxPromptsGlobal is the hard limit of prompts across all projects.
+const MaxPromptsGlobal = 500
+
+// PromptStore provides user prompt-related database operations using GORM.
+type PromptStore struct {
+	db          *gorm.DB
+	cleanupFunc PromptCleanupFunc
+}
+
+// NewPromptStore creates a new prompt store.
+func NewPromptStore(store *Store, cleanupFunc PromptCleanupFunc) *PromptStore {
+	return &PromptStore{
+		db:          store.DB,
+		cleanupFunc: cleanupFunc,
+	}
+}
+
+// SetCleanupFunc sets the callback for when prompts are deleted during cleanup.
+func (s *PromptStore) SetCleanupFunc(fn PromptCleanupFunc) {
+	s.cleanupFunc = fn
+}
+
+// SaveUserPromptWithMatches saves a user prompt with matched observation count.
+// Uses INSERT OR IGNORE to be idempotent - duplicate (session, prompt_number) pairs are silently ignored.
+// This prevents duplicate prompts when the user-prompt hook fires multiple times.
+func (s *PromptStore) SaveUserPromptWithMatches(ctx context.Context, claudeSessionID string, promptNumber int, promptText string, matchedObservations int) (int64, error) {
+	now := time.Now()
+
+	prompt := &UserPrompt{
+		ClaudeSessionID:     claudeSessionID,
+		PromptNumber:        promptNumber,
+		PromptText:          promptText,
+		MatchedObservations: matchedObservations,
+		CreatedAt:           now.Format(time.RFC3339),
+		CreatedAtEpoch:      now.UnixMilli(),
+	}
+
+	// INSERT OR IGNORE using OnConflict
+	result := s.db.WithContext(ctx).
+		Clauses(clause.OnConflict{
+			Columns:   []clause.Column{{Name: "claude_session_id"}, {Name: "prompt_number"}},
+			DoNothing: true,
+		}).
+		Create(prompt)
+
+	if result.Error != nil {
+		return 0, result.Error
+	}
+
+	// If RowsAffected is 0, the insert was ignored (duplicate) - fetch the existing ID
+	if result.RowsAffected == 0 {
+		var existing UserPrompt
+		err := s.db.Where("claude_session_id = ? AND prompt_number = ?", claudeSessionID, promptNumber).
+			First(&existing).Error
+		if err != nil {
+			return 0, err
+		}
+		// Return existing ID without triggering cleanup (already handled when first inserted)
+		return existing.ID, nil
+	}
+
+	// Cleanup old prompts beyond the global limit (async to not block handler)
+	go func() {
+		cleanupCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancel()
+		deletedIDs, _ := s.CleanupOldPrompts(cleanupCtx)
+		if len(deletedIDs) > 0 && s.cleanupFunc != nil {
+			s.cleanupFunc(cleanupCtx, deletedIDs)
+		}
+	}()
+
+	return prompt.ID, nil
+}
+
+// CleanupOldPrompts deletes prompts beyond the global limit.
+// Keeps the most recent MaxPromptsGlobal prompts.
+// Returns the IDs of deleted prompts for downstream cleanup (e.g., vector DB).
+func (s *PromptStore) CleanupOldPrompts(ctx context.Context) ([]int64, error) {
+	// Use a transaction to prevent TOCTOU race condition
+	var idsToDelete []int64
+
+	err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		// Find IDs to keep (most recent MaxPromptsGlobal)
+		var idsToKeep []int64
+		err := tx.Model(&UserPrompt{}).
+			Order("created_at_epoch DESC").
+			Limit(MaxPromptsGlobal).
+			Pluck("id", &idsToKeep).Error
+
+		if err != nil {
+			return err
+		}
+
+		if len(idsToKeep) == 0 {
+			return nil
+		}
+
+		// Find IDs to delete (all IDs not in the keep list)
+		// This happens in the same transaction to prevent race conditions
+		err = tx.Model(&UserPrompt{}).
+			Where("id NOT IN ?", idsToKeep).
+			Pluck("id", &idsToDelete).Error
+
+		if err != nil {
+			return err
+		}
+
+		if len(idsToDelete) == 0 {
+			return nil
+		}
+
+		// Delete the prompts
+		return tx.Delete(&UserPrompt{}, idsToDelete).Error
+	})
+
+	if err != nil {
+		return nil, err
+	}
+
+	return idsToDelete, nil
+}
+
+// GetPromptsByIDs retrieves user prompts by a list of IDs.
+func (s *PromptStore) GetPromptsByIDs(ctx context.Context, ids []int64, orderBy string, limit int) ([]*models.UserPromptWithSession, error) {
+	if len(ids) == 0 {
+		return nil, nil
+	}
+
+	var results []struct {
+		UserPrompt
+		Project      sql.NullString `gorm:"column:project"`
+		SDKSessionID sql.NullString `gorm:"column:sdk_session_id"`
+	}
+
+	query := s.db.WithContext(ctx).
+		Table("user_prompts up").
+		Select("up.id, up.claude_session_id, up.prompt_number, up.prompt_text, "+
+			"COALESCE(up.matched_observations, 0) as matched_observations, "+
+			"up.created_at, up.created_at_epoch, "+
+			"COALESCE(s.project, '') as project, "+
+			"COALESCE(s.sdk_session_id, '') as sdk_session_id").
+		Joins("LEFT JOIN sdk_sessions s ON up.claude_session_id = s.claude_session_id").
+		Where("up.id IN ?", ids)
+
+	// Apply ordering
+	switch orderBy {
+	case "date_asc":
+		query = query.Order("up.created_at_epoch ASC")
+	case "date_desc", "default", "":
+		query = query.Order("up.created_at_epoch DESC")
+	}
+
+	// Apply limit
+	if limit > 0 {
+		query = query.Limit(limit)
+	}
+
+	err := query.Scan(&results).Error
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelUserPromptsWithSession(results), nil
+}
+
+// GetAllRecentUserPrompts retrieves recent user prompts across all projects.
+func (s *PromptStore) GetAllRecentUserPrompts(ctx context.Context, limit int) ([]*models.UserPromptWithSession, error) {
+	var results []struct {
+		UserPrompt
+		Project      sql.NullString `gorm:"column:project"`
+		SDKSessionID sql.NullString `gorm:"column:sdk_session_id"`
+	}
+
+	query := s.db.WithContext(ctx).
+		Table("user_prompts up").
+		Select("up.id, up.claude_session_id, up.prompt_number, up.prompt_text, " +
+			"COALESCE(up.matched_observations, 0) as matched_observations, " +
+			"up.created_at, up.created_at_epoch, " +
+			"COALESCE(s.project, '') as project, " +
+			"COALESCE(s.sdk_session_id, '') as sdk_session_id").
+		Joins("LEFT JOIN sdk_sessions s ON up.claude_session_id = s.claude_session_id").
+		Order("up.created_at_epoch DESC").
+		Limit(limit)
+
+	err := query.Scan(&results).Error
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelUserPromptsWithSession(results), nil
+}
+
+// GetAllPrompts retrieves all user prompts (for vector rebuild).
+func (s *PromptStore) GetAllPrompts(ctx context.Context) ([]*models.UserPromptWithSession, error) {
+	var results []struct {
+		UserPrompt
+		Project      sql.NullString `gorm:"column:project"`
+		SDKSessionID sql.NullString `gorm:"column:sdk_session_id"`
+	}
+
+	query := s.db.WithContext(ctx).
+		Table("user_prompts up").
+		Select("up.id, up.claude_session_id, up.prompt_number, up.prompt_text, " +
+			"COALESCE(up.matched_observations, 0) as matched_observations, " +
+			"up.created_at, up.created_at_epoch, " +
+			"COALESCE(s.project, '') as project, " +
+			"COALESCE(s.sdk_session_id, '') as sdk_session_id").
+		Joins("LEFT JOIN sdk_sessions s ON up.claude_session_id = s.claude_session_id").
+		Order("up.id")
+
+	err := query.Scan(&results).Error
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelUserPromptsWithSession(results), nil
+}
+
+// FindRecentPromptByText finds a recent prompt by exact text match within a time window.
+// Returns (promptID, promptNumber, found).
+func (s *PromptStore) FindRecentPromptByText(ctx context.Context, claudeSessionID, promptText string, withinSeconds int) (int64, int, bool) {
+	cutoffEpoch := time.Now().Add(-time.Duration(withinSeconds) * time.Second).UnixMilli()
+
+	var prompt UserPrompt
+	err := s.db.WithContext(ctx).
+		Where("claude_session_id = ? AND prompt_text = ? AND created_at_epoch >= ?",
+			claudeSessionID, promptText, cutoffEpoch).
+		Order("created_at_epoch DESC").
+		First(&prompt).Error
+
+	if err != nil {
+		return 0, 0, false
+	}
+
+	return prompt.ID, prompt.PromptNumber, true
+}
+
+// GetRecentUserPromptsByProject retrieves recent user prompts for a specific project.
+func (s *PromptStore) GetRecentUserPromptsByProject(ctx context.Context, project string, limit int) ([]*models.UserPromptWithSession, error) {
+	var results []struct {
+		UserPrompt
+		Project      sql.NullString `gorm:"column:project"`
+		SDKSessionID sql.NullString `gorm:"column:sdk_session_id"`
+	}
+
+	query := s.db.WithContext(ctx).
+		Table("user_prompts up").
+		Select("up.id, up.claude_session_id, up.prompt_number, up.prompt_text, "+
+			"COALESCE(up.matched_observations, 0) as matched_observations, "+
+			"up.created_at, up.created_at_epoch, "+
+			"COALESCE(s.project, '') as project, "+
+			"COALESCE(s.sdk_session_id, '') as sdk_session_id").
+		Joins("LEFT JOIN sdk_sessions s ON up.claude_session_id = s.claude_session_id").
+		Where("s.project = ?", project).
+		Order("up.created_at_epoch DESC").
+		Limit(limit)
+
+	err := query.Scan(&results).Error
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelUserPromptsWithSession(results), nil
+}
+
+// toModelUserPromptsWithSession converts query results to pkg/models.UserPromptWithSession.
+func toModelUserPromptsWithSession(results []struct {
+	UserPrompt
+	Project      sql.NullString `gorm:"column:project"`
+	SDKSessionID sql.NullString `gorm:"column:sdk_session_id"`
+}) []*models.UserPromptWithSession {
+	prompts := make([]*models.UserPromptWithSession, len(results))
+	for i, r := range results {
+		project := ""
+		if r.Project.Valid {
+			project = r.Project.String
+		}
+
+		sdkSessionID := ""
+		if r.SDKSessionID.Valid {
+			sdkSessionID = r.SDKSessionID.String
+		}
+
+		prompts[i] = &models.UserPromptWithSession{
+			UserPrompt: models.UserPrompt{
+				ID:                  r.ID,
+				ClaudeSessionID:     r.ClaudeSessionID,
+				PromptNumber:        r.PromptNumber,
+				PromptText:          r.PromptText,
+				MatchedObservations: r.MatchedObservations,
+				CreatedAt:           r.CreatedAt,
+				CreatedAtEpoch:      r.CreatedAtEpoch,
+			},
+			Project:      project,
+			SDKSessionID: sdkSessionID,
+		}
+	}
+	return prompts
+}

internal/db/gorm/prompt_store_test.go

@@ -0,0 +1,396 @@
+//go:build fts5
+
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm/logger"
+)
+
+// testPromptStore creates a PromptStore with a temporary database for testing.
+func testPromptStore(t *testing.T) (*PromptStore, *Store, func()) {
+	t.Helper()
+
+	tmpDir, err := os.MkdirTemp("", "gorm_prompt_test_*")
+	if err != nil {
+		t.Fatalf("create temp dir: %v", err)
+	}
+
+	dbPath := filepath.Join(tmpDir, "test.db")
+	cfg := Config{
+		Path:     dbPath,
+		MaxConns: 4,
+		LogLevel: logger.Silent,
+	}
+
+	store, err := NewStore(cfg)
+	if err != nil {
+		os.RemoveAll(tmpDir)
+		t.Fatalf("NewStore failed: %v", err)
+	}
+
+	promptStore := NewPromptStore(store, nil)
+
+	cleanup := func() {
+		store.Close()
+		os.RemoveAll(tmpDir)
+	}
+
+	return promptStore, store, cleanup
+}
+
+func TestPromptStore_SaveUserPromptWithMatches(t *testing.T) {
+	promptStore, store, cleanup := testPromptStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create a session first
+	sessionStore := NewSessionStore(store)
+	_, err := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+	require.NoError(t, err)
+
+	// Save a prompt
+	id, err := promptStore.SaveUserPromptWithMatches(ctx, "claude-1", 1, "What is the codebase structure?", 5)
+	require.NoError(t, err)
+	assert.Greater(t, id, int64(0))
+}
+
+func TestPromptStore_SaveUserPromptWithMatches_Idempotency(t *testing.T) {
+	promptStore, _, cleanup := testPromptStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Save the same prompt twice (same claudeSessionID + promptNumber)
+	id1, err := promptStore.SaveUserPromptWithMatches(ctx, "claude-1", 1, "Test prompt", 3)
+	require.NoError(t, err)
+
+	id2, err := promptStore.SaveUserPromptWithMatches(ctx, "claude-1", 1, "Different text", 5)
+	require.NoError(t, err)
+
+	// Should return the same ID (INSERT OR IGNORE)
+	assert.Equal(t, id1, id2, "Duplicate prompts should return same ID")
+}
+
+func TestPromptStore_SaveUserPromptWithMatches_AsyncCleanup(t *testing.T) {
+	promptStore, _, cleanup := testPromptStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Track cleanup calls
+	var cleanupMutex sync.Mutex
+	cleanupCalled := false
+	var cleanupIDs []int64
+
+	cleanupFunc := func(ctx context.Context, deletedIDs []int64) {
+		cleanupMutex.Lock()
+		defer cleanupMutex.Unlock()
+		cleanupCalled = true
+		cleanupIDs = deletedIDs
+	}
+
+	promptStore.cleanupFunc = cleanupFunc
+
+	// Save prompts beyond the global limit (MaxPromptsGlobal = 500)
+	// Insert with slower pacing to avoid database lock contention
+	for i := 0; i < 505; i++ {
+		_, err := promptStore.SaveUserPromptWithMatches(ctx, "claude-1", i+1, "Prompt", 1)
+		require.NoError(t, err)
+		if i > 500 {
+			time.Sleep(5 * time.Millisecond) // Slow down after hitting limit
+		}
+	}
+
+	// Wait longer for async cleanup to complete
+	time.Sleep(500 * time.Millisecond)
+
+	// Verify cleanup was called
+	cleanupMutex.Lock()
+	defer cleanupMutex.Unlock()
+	assert.True(t, cleanupCalled, "Cleanup function should have been called")
+	assert.NotEmpty(t, cleanupIDs, "Cleanup should have deleted some prompts")
+}
+
+func TestPromptStore_CleanupOldPrompts(t *testing.T) {
+	promptStore, _, cleanup := testPromptStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Save prompts beyond the limit
+	// Async cleanup should fire after each insert beyond 500
+	for i := 0; i < 505; i++ {
+		_, err := promptStore.SaveUserPromptWithMatches(ctx, "claude-1", i+1, "Prompt", 1)
+		require.NoError(t, err)
+	}
+
+	// Wait for all async cleanups to complete
+	time.Sleep(1 * time.Second)
+
+	// After async cleanup, we should have at most 500 prompts
+	remaining, err := promptStore.GetAllPrompts(ctx)
+	require.NoError(t, err)
+	assert.LessOrEqual(t, len(remaining), MaxPromptsGlobal, "Should have at most %d prompts after async cleanup", MaxPromptsGlobal)
+}
+
+func TestPromptStore_GetPromptsByIDs(t *testing.T) {
+	promptStore, _, cleanup := testPromptStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Save multiple prompts
+	var ids []int64
+	for i := 1; i <= 3; i++ {
+		id, err := promptStore.SaveUserPromptWithMatches(ctx, "claude-1", i, "Prompt", i)
+		require.NoError(t, err)
+		ids = append(ids, id)
+		time.Sleep(10 * time.Millisecond) // Ensure different timestamps
+	}
+
+	tests := []struct {
+		name     string
+		orderBy  string
+		expected []int64
+	}{
+		{
+			name:     "Default ordering - date desc",
+			orderBy:  "default",
+			expected: []int64{ids[2], ids[1], ids[0]}, // Newest to oldest
+		},
+		{
+			name:     "Date ascending",
+			orderBy:  "date_asc",
+			expected: []int64{ids[0], ids[1], ids[2]}, // Oldest to newest
+		},
+		{
+			name:     "Date descending",
+			orderBy:  "date_desc",
+			expected: []int64{ids[2], ids[1], ids[0]}, // Newest to oldest
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			prompts, err := promptStore.GetPromptsByIDs(ctx, ids, tt.orderBy, 10)
+			require.NoError(t, err)
+			require.Len(t, prompts, 3)
+
+			// Verify ordering
+			for i, prompt := range prompts {
+				assert.Equal(t, tt.expected[i], prompt.ID, "Position %d should have ID %d", i, tt.expected[i])
+			}
+		})
+	}
+}
+
+func TestPromptStore_GetPromptsByIDs_Limit(t *testing.T) {
+	promptStore, _, cleanup := testPromptStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Save multiple prompts
+	var ids []int64
+	for i := 1; i <= 5; i++ {
+		id, err := promptStore.SaveUserPromptWithMatches(ctx, "claude-1", i, "Prompt", i)
+		require.NoError(t, err)
+		ids = append(ids, id)
+	}
+
+	// Get with limit
+	prompts, err := promptStore.GetPromptsByIDs(ctx, ids, "default", 3)
+	require.NoError(t, err)
+	assert.Len(t, prompts, 3)
+}
+
+func TestPromptStore_GetPromptsByIDs_EmptyInput(t *testing.T) {
+	promptStore, _, cleanup := testPromptStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Get with empty IDs
+	prompts, err := promptStore.GetPromptsByIDs(ctx, []int64{}, "default", 10)
+	require.NoError(t, err)
+	assert.Nil(t, prompts)
+}
+
+func TestPromptStore_GetPromptsByIDs_WithSession(t *testing.T) {
+	promptStore, store, cleanup := testPromptStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create a session
+	sessionStore := NewSessionStore(store)
+	_, err := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+	require.NoError(t, err)
+
+	// Save a prompt
+	id, err := promptStore.SaveUserPromptWithMatches(ctx, "claude-1", 1, "Test prompt", 5)
+	require.NoError(t, err)
+
+	// Get with session join
+	prompts, err := promptStore.GetPromptsByIDs(ctx, []int64{id}, "default", 10)
+	require.NoError(t, err)
+	require.Len(t, prompts, 1)
+
+	// Verify session data is populated
+	assert.Equal(t, "test-project", prompts[0].Project)
+	assert.NotEmpty(t, prompts[0].SDKSessionID)
+}
+
+func TestPromptStore_GetAllRecentUserPrompts(t *testing.T) {
+	promptStore, _, cleanup := testPromptStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Save prompts across multiple sessions with timestamps
+	for i := 1; i <= 3; i++ {
+		_, err := promptStore.SaveUserPromptWithMatches(ctx, "claude-1", i, "Prompt A", i)
+		require.NoError(t, err)
+		time.Sleep(10 * time.Millisecond) // Ensure different timestamps
+	}
+
+	for i := 1; i <= 2; i++ {
+		_, err := promptStore.SaveUserPromptWithMatches(ctx, "claude-2", i, "Prompt B", i)
+		require.NoError(t, err)
+		time.Sleep(10 * time.Millisecond) // Ensure different timestamps
+	}
+
+	// Get all recent prompts
+	prompts, err := promptStore.GetAllRecentUserPrompts(ctx, 10)
+	require.NoError(t, err)
+	assert.Len(t, prompts, 5)
+
+	// Verify ordering (most recent first) - last inserted should be first
+	assert.Equal(t, "claude-2", prompts[0].ClaudeSessionID)
+	assert.Equal(t, 2, prompts[0].PromptNumber)
+}
+
+func TestPromptStore_GetAllPrompts(t *testing.T) {
+	promptStore, _, cleanup := testPromptStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Save prompts
+	for i := 1; i <= 5; i++ {
+		_, err := promptStore.SaveUserPromptWithMatches(ctx, "claude-1", i, "Prompt", i)
+		require.NoError(t, err)
+	}
+
+	// Wait for any async cleanup to complete (longer wait for race detector)
+	time.Sleep(500 * time.Millisecond)
+
+	// Get all prompts (for vector rebuild)
+	prompts, err := promptStore.GetAllPrompts(ctx)
+	require.NoError(t, err)
+	assert.Len(t, prompts, 5)
+
+	// Verify ordering by ID
+	for i := 0; i < len(prompts)-1; i++ {
+		assert.Less(t, prompts[i].ID, prompts[i+1].ID)
+	}
+}
+
+func TestPromptStore_FindRecentPromptByText(t *testing.T) {
+	promptStore, _, cleanup := testPromptStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Save a prompt
+	id, err := promptStore.SaveUserPromptWithMatches(ctx, "claude-1", 1, "What is the architecture?", 3)
+	require.NoError(t, err)
+
+	// Find by exact text match within time window
+	foundID, foundNumber, found := promptStore.FindRecentPromptByText(ctx, "claude-1", "What is the architecture?", 60)
+	assert.True(t, found, "Should find the prompt")
+	assert.Equal(t, id, foundID)
+	assert.Equal(t, 1, foundNumber)
+
+	// Try to find with different text
+	_, _, notFound := promptStore.FindRecentPromptByText(ctx, "claude-1", "Different text", 60)
+	assert.False(t, notFound, "Should not find a different prompt")
+
+	// Try to find outside time window
+	time.Sleep(100 * time.Millisecond)
+	_, _, notFound = promptStore.FindRecentPromptByText(ctx, "claude-1", "What is the architecture?", 0)
+	assert.False(t, notFound, "Should not find prompt outside time window")
+}
+
+func TestPromptStore_GetRecentUserPromptsByProject(t *testing.T) {
+	promptStore, store, cleanup := testPromptStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create sessions for different projects
+	sessionStore := NewSessionStore(store)
+	_, err := sessionStore.CreateSDKSession(ctx, "claude-1", "project-a", "")
+	require.NoError(t, err)
+	_, err = sessionStore.CreateSDKSession(ctx, "claude-2", "project-b", "")
+	require.NoError(t, err)
+
+	// Save prompts for project-a
+	for i := 1; i <= 3; i++ {
+		_, err := promptStore.SaveUserPromptWithMatches(ctx, "claude-1", i, "Prompt A", i)
+		require.NoError(t, err)
+	}
+
+	// Save prompts for project-b
+	for i := 1; i <= 2; i++ {
+		_, err := promptStore.SaveUserPromptWithMatches(ctx, "claude-2", i, "Prompt B", i)
+		require.NoError(t, err)
+	}
+
+	// Get prompts for project-a
+	prompts, err := promptStore.GetRecentUserPromptsByProject(ctx, "project-a", 10)
+	require.NoError(t, err)
+	assert.Len(t, prompts, 3)
+
+	// Verify all prompts are from project-a
+	for _, prompt := range prompts {
+		assert.Equal(t, "project-a", prompt.Project)
+	}
+}
+
+func TestPromptStore_GetRecentUserPromptsByProject_Limit(t *testing.T) {
+	promptStore, store, cleanup := testPromptStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create session
+	sessionStore := NewSessionStore(store)
+	_, err := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+	require.NoError(t, err)
+
+	// Save multiple prompts
+	for i := 1; i <= 10; i++ {
+		_, err := promptStore.SaveUserPromptWithMatches(ctx, "claude-1", i, "Prompt", i)
+		require.NoError(t, err)
+	}
+
+	// Wait for any async cleanup to complete
+	time.Sleep(100 * time.Millisecond)
+
+	// Get with limit
+	prompts, err := promptStore.GetRecentUserPromptsByProject(ctx, "test-project", 5)
+	require.NoError(t, err)
+	assert.Len(t, prompts, 5)
+}

internal/db/gorm/relation_store.go

@@ -0,0 +1,383 @@
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"context"
+	"database/sql"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+)
+
+// RelationStore provides relation-related database operations using GORM.
+type RelationStore struct {
+	db *gorm.DB
+}
+
+// NewRelationStore creates a new relation store.
+func NewRelationStore(store *Store) *RelationStore {
+	return &RelationStore{
+		db: store.DB,
+	}
+}
+
+// StoreRelation stores a new observation relation.
+// Uses INSERT OR IGNORE to handle duplicate (source_id, target_id, relation_type) combinations.
+func (s *RelationStore) StoreRelation(ctx context.Context, relation *models.ObservationRelation) (int64, error) {
+	dbRelation := &ObservationRelation{
+		SourceID:        relation.SourceID,
+		TargetID:        relation.TargetID,
+		RelationType:    relation.RelationType,
+		Confidence:      relation.Confidence,
+		DetectionSource: relation.DetectionSource,
+		CreatedAt:       relation.CreatedAt,
+		CreatedAtEpoch:  relation.CreatedAtEpoch,
+	}
+
+	// Handle nullable fields
+	if relation.Reason != "" {
+		dbRelation.Reason = sql.NullString{String: relation.Reason, Valid: true}
+	}
+
+	// INSERT OR IGNORE using OnConflict
+	result := s.db.WithContext(ctx).
+		Clauses(clause.OnConflict{
+			Columns:   []clause.Column{{Name: "source_id"}, {Name: "target_id"}, {Name: "relation_type"}},
+			DoNothing: true,
+		}).
+		Create(dbRelation)
+
+	if result.Error != nil {
+		return 0, result.Error
+	}
+
+	// If RowsAffected is 0, the insert was ignored (duplicate)
+	if result.RowsAffected == 0 {
+		var existing ObservationRelation
+		err := s.db.Where("source_id = ? AND target_id = ? AND relation_type = ?",
+			relation.SourceID, relation.TargetID, relation.RelationType).
+			First(&existing).Error
+		if err != nil {
+			return 0, err
+		}
+		return existing.ID, nil
+	}
+
+	return dbRelation.ID, nil
+}
+
+// StoreRelations stores multiple relations in a single transaction.
+func (s *RelationStore) StoreRelations(ctx context.Context, relations []*models.ObservationRelation) error {
+	if len(relations) == 0 {
+		return nil
+	}
+
+	return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		for _, rel := range relations {
+			dbRelation := &ObservationRelation{
+				SourceID:        rel.SourceID,
+				TargetID:        rel.TargetID,
+				RelationType:    rel.RelationType,
+				Confidence:      rel.Confidence,
+				DetectionSource: rel.DetectionSource,
+				CreatedAt:       rel.CreatedAt,
+				CreatedAtEpoch:  rel.CreatedAtEpoch,
+			}
+
+			if rel.Reason != "" {
+				dbRelation.Reason = sql.NullString{String: rel.Reason, Valid: true}
+			}
+
+			result := tx.Clauses(clause.OnConflict{
+				Columns:   []clause.Column{{Name: "source_id"}, {Name: "target_id"}, {Name: "relation_type"}},
+				DoNothing: true,
+			}).Create(dbRelation)
+
+			if result.Error != nil {
+				return result.Error
+			}
+		}
+		return nil
+	})
+}
+
+// GetRelationsByObservationID retrieves all relations involving an observation (as source or target).
+func (s *RelationStore) GetRelationsByObservationID(ctx context.Context, obsID int64) ([]*models.ObservationRelation, error) {
+	var relations []ObservationRelation
+
+	err := s.db.WithContext(ctx).
+		Where("source_id = ? OR target_id = ?", obsID, obsID).
+		Order("confidence DESC, created_at_epoch DESC").
+		Find(&relations).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelRelations(relations), nil
+}
+
+// GetOutgoingRelations retrieves relations where the observation is the source.
+func (s *RelationStore) GetOutgoingRelations(ctx context.Context, obsID int64) ([]*models.ObservationRelation, error) {
+	var relations []ObservationRelation
+
+	err := s.db.WithContext(ctx).
+		Where("source_id = ?", obsID).
+		Order("confidence DESC, created_at_epoch DESC").
+		Find(&relations).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelRelations(relations), nil
+}
+
+// GetIncomingRelations retrieves relations where the observation is the target.
+func (s *RelationStore) GetIncomingRelations(ctx context.Context, obsID int64) ([]*models.ObservationRelation, error) {
+	var relations []ObservationRelation
+
+	err := s.db.WithContext(ctx).
+		Where("target_id = ?", obsID).
+		Order("confidence DESC, created_at_epoch DESC").
+		Find(&relations).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelRelations(relations), nil
+}
+
+// GetRelationsByType retrieves all relations of a specific type.
+func (s *RelationStore) GetRelationsByType(ctx context.Context, relationType models.RelationType, limit int) ([]*models.ObservationRelation, error) {
+	var relations []ObservationRelation
+
+	err := s.db.WithContext(ctx).
+		Where("relation_type = ?", relationType).
+		Order("confidence DESC, created_at_epoch DESC").
+		Limit(limit).
+		Find(&relations).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelRelations(relations), nil
+}
+
+// GetRelationsWithDetails retrieves relations with observation titles for display.
+func (s *RelationStore) GetRelationsWithDetails(ctx context.Context, obsID int64) ([]*models.RelationWithDetails, error) {
+	var results []struct {
+		ObservationRelation
+		SourceTitle sql.NullString `gorm:"column:source_title"`
+		TargetTitle sql.NullString `gorm:"column:target_title"`
+		SourceType  string         `gorm:"column:source_type"`
+		TargetType  string         `gorm:"column:target_type"`
+	}
+
+	err := s.db.WithContext(ctx).
+		Table("observation_relations r").
+		Select("r.*, "+
+			"COALESCE(src.title, '') as source_title, "+
+			"COALESCE(tgt.title, '') as target_title, "+
+			"src.type as source_type, "+
+			"tgt.type as target_type").
+		Joins("JOIN observations src ON src.id = r.source_id").
+		Joins("JOIN observations tgt ON tgt.id = r.target_id").
+		Where("r.source_id = ? OR r.target_id = ?", obsID, obsID).
+		Order("r.confidence DESC, r.created_at_epoch DESC").
+		Scan(&results).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	relations := make([]*models.RelationWithDetails, len(results))
+	for i, r := range results {
+		relations[i] = &models.RelationWithDetails{
+			Relation:    toModelRelation(&r.ObservationRelation),
+			SourceTitle: r.SourceTitle.String,
+			TargetTitle: r.TargetTitle.String,
+			SourceType:  models.ObservationType(r.SourceType),
+			TargetType:  models.ObservationType(r.TargetType),
+		}
+	}
+
+	return relations, nil
+}
+
+// GetRelationGraph retrieves a relation graph centered on an observation.
+// This returns all observations within N hops from the center.
+func (s *RelationStore) GetRelationGraph(ctx context.Context, centerID int64, maxDepth int) (*models.RelationGraph, error) {
+	// Get all relations involving the center observation
+	relations, err := s.GetRelationsWithDetails(ctx, centerID)
+	if err != nil {
+		return nil, err
+	}
+
+	graph := &models.RelationGraph{
+		CenterID:  centerID,
+		Relations: relations,
+	}
+
+	// If depth > 1, recursively get relations for connected observations
+	if maxDepth > 1 {
+		visited := map[int64]bool{centerID: true}
+		toVisit := make([]int64, 0)
+
+		// Collect IDs of directly connected observations
+		for _, r := range relations {
+			if !visited[r.Relation.SourceID] {
+				toVisit = append(toVisit, r.Relation.SourceID)
+				visited[r.Relation.SourceID] = true
+			}
+			if !visited[r.Relation.TargetID] {
+				toVisit = append(toVisit, r.Relation.TargetID)
+				visited[r.Relation.TargetID] = true
+			}
+		}
+
+		// Get relations for connected observations (depth - 1)
+		for depth := 1; depth < maxDepth && len(toVisit) > 0; depth++ {
+			nextLevel := make([]int64, 0)
+			for _, obsID := range toVisit {
+				moreRelations, err := s.GetRelationsWithDetails(ctx, obsID)
+				if err != nil {
+					continue
+				}
+				for _, r := range moreRelations {
+					// Avoid duplicates
+					exists := false
+					for _, existing := range graph.Relations {
+						if existing.Relation.ID == r.Relation.ID {
+							exists = true
+							break
+						}
+					}
+					if !exists {
+						graph.Relations = append(graph.Relations, r)
+					}
+
+					// Queue next level
+					if !visited[r.Relation.SourceID] {
+						nextLevel = append(nextLevel, r.Relation.SourceID)
+						visited[r.Relation.SourceID] = true
+					}
+					if !visited[r.Relation.TargetID] {
+						nextLevel = append(nextLevel, r.Relation.TargetID)
+						visited[r.Relation.TargetID] = true
+					}
+				}
+			}
+			toVisit = nextLevel
+		}
+	}
+
+	return graph, nil
+}
+
+// DeleteRelationsByObservationID deletes all relations involving an observation.
+// Called when an observation is deleted.
+func (s *RelationStore) DeleteRelationsByObservationID(ctx context.Context, obsID int64) error {
+	result := s.db.WithContext(ctx).
+		Where("source_id = ? OR target_id = ?", obsID, obsID).
+		Delete(&ObservationRelation{})
+
+	return result.Error
+}
+
+// GetRelationCount returns the count of relations for an observation.
+func (s *RelationStore) GetRelationCount(ctx context.Context, obsID int64) (int, error) {
+	var count int64
+	err := s.db.WithContext(ctx).
+		Model(&ObservationRelation{}).
+		Where("source_id = ? OR target_id = ?", obsID, obsID).
+		Count(&count).Error
+
+	return int(count), err
+}
+
+// GetTotalRelationCount returns the total count of all relations.
+func (s *RelationStore) GetTotalRelationCount(ctx context.Context) (int, error) {
+	var count int64
+	err := s.db.WithContext(ctx).
+		Model(&ObservationRelation{}).
+		Count(&count).Error
+
+	return int(count), err
+}
+
+// GetHighConfidenceRelations retrieves relations with confidence above threshold.
+func (s *RelationStore) GetHighConfidenceRelations(ctx context.Context, minConfidence float64, limit int) ([]*models.ObservationRelation, error) {
+	var relations []ObservationRelation
+
+	err := s.db.WithContext(ctx).
+		Where("confidence >= ?", minConfidence).
+		Order("confidence DESC, created_at_epoch DESC").
+		Limit(limit).
+		Find(&relations).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelRelations(relations), nil
+}
+
+// UpdateRelationConfidence updates the confidence of a relation.
+func (s *RelationStore) UpdateRelationConfidence(ctx context.Context, relationID int64, newConfidence float64) error {
+	result := s.db.WithContext(ctx).
+		Model(&ObservationRelation{}).
+		Where("id = ?", relationID).
+		Update("confidence", newConfidence)
+
+	return result.Error
+}
+
+// GetRelatedObservationIDs returns IDs of observations related to the given one.
+// This is useful for expanding search results.
+// Uses CASE expression for bidirectional ID lookup (GORM doesn't support this well, so we use raw SQL).
+func (s *RelationStore) GetRelatedObservationIDs(ctx context.Context, obsID int64, minConfidence float64) ([]int64, error) {
+	var ids []int64
+
+	err := s.db.WithContext(ctx).
+		Raw("SELECT DISTINCT CASE WHEN source_id = ? THEN target_id ELSE source_id END as related_id "+
+			"FROM observation_relations "+
+			"WHERE (source_id = ? OR target_id = ?) AND confidence >= ?",
+			obsID, obsID, obsID, minConfidence).
+		Pluck("related_id", &ids).Error
+
+	return ids, err
+}
+
+// toModelRelation converts a GORM ObservationRelation to a pkg/models ObservationRelation.
+func toModelRelation(r *ObservationRelation) *models.ObservationRelation {
+	relation := &models.ObservationRelation{
+		ID:              r.ID,
+		SourceID:        r.SourceID,
+		TargetID:        r.TargetID,
+		RelationType:    r.RelationType,
+		Confidence:      r.Confidence,
+		DetectionSource: r.DetectionSource,
+		CreatedAt:       r.CreatedAt,
+		CreatedAtEpoch:  r.CreatedAtEpoch,
+	}
+
+	if r.Reason.Valid {
+		relation.Reason = r.Reason.String
+	}
+
+	return relation
+}
+
+// toModelRelations converts a slice of GORM ObservationRelations to pkg/models ObservationRelations.
+func toModelRelations(relations []ObservationRelation) []*models.ObservationRelation {
+	result := make([]*models.ObservationRelation, len(relations))
+	for i, r := range relations {
+		result[i] = toModelRelation(&r)
+	}
+	return result
+}

internal/db/gorm/relation_store_test.go

@@ -0,0 +1,306 @@
+//go:build fts5
+
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm/logger"
+
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+)
+
+func testRelationStore(t *testing.T) (*RelationStore, *Store, func()) {
+	t.Helper()
+
+	tmpDir, err := os.MkdirTemp("", "gorm_relation_test_*")
+	if err != nil {
+		t.Fatalf("create temp dir: %v", err)
+	}
+
+	dbPath := filepath.Join(tmpDir, "test.db")
+	cfg := Config{
+		Path:     dbPath,
+		MaxConns: 4,
+		LogLevel: logger.Silent,
+	}
+
+	store, err := NewStore(cfg)
+	if err != nil {
+		os.RemoveAll(tmpDir)
+		t.Fatalf("NewStore failed: %v", err)
+	}
+
+	relationStore := NewRelationStore(store)
+
+	cleanup := func() {
+		store.Close()
+		os.RemoveAll(tmpDir)
+	}
+
+	return relationStore, store, cleanup
+}
+
+func TestRelationStore_StoreRelation(t *testing.T) {
+	relationStore, _, cleanup := testRelationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+	now := time.Now()
+
+	relation := &models.ObservationRelation{
+		SourceID:        1,
+		TargetID:        2,
+		RelationType:    models.RelationCauses,
+		Confidence:      0.8,
+		DetectionSource: models.DetectionSourceFileOverlap,
+		Reason:          "Test relation",
+		CreatedAt:       now.Format(time.RFC3339),
+		CreatedAtEpoch:  now.UnixMilli(),
+	}
+
+	id, err := relationStore.StoreRelation(ctx, relation)
+	require.NoError(t, err)
+	assert.Greater(t, id, int64(0))
+}
+
+func TestRelationStore_StoreRelation_Idempotency(t *testing.T) {
+	relationStore, _, cleanup := testRelationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+	now := time.Now()
+
+	relation := &models.ObservationRelation{
+		SourceID:        1,
+		TargetID:        2,
+		RelationType:    models.RelationCauses,
+		Confidence:      0.8,
+		DetectionSource: models.DetectionSourceFileOverlap,
+		CreatedAt:       now.Format(time.RFC3339),
+		CreatedAtEpoch:  now.UnixMilli(),
+	}
+
+	id1, err := relationStore.StoreRelation(ctx, relation)
+	require.NoError(t, err)
+
+	// Store again with same source/target/type - should return same ID
+	id2, err := relationStore.StoreRelation(ctx, relation)
+	require.NoError(t, err)
+	assert.Equal(t, id1, id2)
+}
+
+func TestRelationStore_StoreRelations(t *testing.T) {
+	relationStore, _, cleanup := testRelationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+	now := time.Now()
+
+	relations := []*models.ObservationRelation{
+		{
+			SourceID:        1,
+			TargetID:        2,
+			RelationType:    models.RelationCauses,
+			Confidence:      0.8,
+			DetectionSource: models.DetectionSourceFileOverlap,
+			CreatedAt:       now.Format(time.RFC3339),
+			CreatedAtEpoch:  now.UnixMilli(),
+		},
+		{
+			SourceID:        2,
+			TargetID:        3,
+			RelationType:    models.RelationFixes,
+			Confidence:      0.9,
+			DetectionSource: models.DetectionSourceTemporalProximity,
+			CreatedAt:       now.Format(time.RFC3339),
+			CreatedAtEpoch:  now.UnixMilli(),
+		},
+	}
+
+	err := relationStore.StoreRelations(ctx, relations)
+	require.NoError(t, err)
+
+	// Verify both were stored
+	count, err := relationStore.GetTotalRelationCount(ctx)
+	require.NoError(t, err)
+	assert.Equal(t, 2, count)
+}
+
+func TestRelationStore_GetRelationsByObservationID(t *testing.T) {
+	relationStore, _, cleanup := testRelationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+	now := time.Now()
+
+	// Create relations involving observation 2
+	relations := []*models.ObservationRelation{
+		{
+			SourceID:        1,
+			TargetID:        2,
+			RelationType:    models.RelationCauses,
+			Confidence:      0.8,
+			DetectionSource: models.DetectionSourceFileOverlap,
+			CreatedAt:       now.Format(time.RFC3339),
+			CreatedAtEpoch:  now.UnixMilli(),
+		},
+		{
+			SourceID:        2,
+			TargetID:        3,
+			RelationType:    models.RelationFixes,
+			Confidence:      0.9,
+			DetectionSource: models.DetectionSourceTemporalProximity,
+			CreatedAt:       now.Format(time.RFC3339),
+			CreatedAtEpoch:  now.UnixMilli(),
+		},
+	}
+
+	err := relationStore.StoreRelations(ctx, relations)
+	require.NoError(t, err)
+
+	// Get relations for observation 2 (involved in both)
+	result, err := relationStore.GetRelationsByObservationID(ctx, 2)
+	require.NoError(t, err)
+	assert.Len(t, result, 2)
+}
+
+func TestRelationStore_GetOutgoingAndIncomingRelations(t *testing.T) {
+	relationStore, _, cleanup := testRelationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+	now := time.Now()
+
+	relations := []*models.ObservationRelation{
+		{
+			SourceID:        2,
+			TargetID:        1,
+			RelationType:    models.RelationCauses,
+			Confidence:      0.8,
+			DetectionSource: models.DetectionSourceFileOverlap,
+			CreatedAt:       now.Format(time.RFC3339),
+			CreatedAtEpoch:  now.UnixMilli(),
+		},
+		{
+			SourceID:        3,
+			TargetID:        2,
+			RelationType:    models.RelationFixes,
+			Confidence:      0.9,
+			DetectionSource: models.DetectionSourceTemporalProximity,
+			CreatedAt:       now.Format(time.RFC3339),
+			CreatedAtEpoch:  now.UnixMilli(),
+		},
+	}
+
+	err := relationStore.StoreRelations(ctx, relations)
+	require.NoError(t, err)
+
+	// Observation 2 has 1 outgoing (to 1) and 1 incoming (from 3)
+	outgoing, err := relationStore.GetOutgoingRelations(ctx, 2)
+	require.NoError(t, err)
+	assert.Len(t, outgoing, 1)
+	assert.Equal(t, int64(1), outgoing[0].TargetID)
+
+	incoming, err := relationStore.GetIncomingRelations(ctx, 2)
+	require.NoError(t, err)
+	assert.Len(t, incoming, 1)
+	assert.Equal(t, int64(3), incoming[0].SourceID)
+}
+
+func TestRelationStore_GetRelationCount(t *testing.T) {
+	relationStore, _, cleanup := testRelationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+	now := time.Now()
+
+	relations := []*models.ObservationRelation{
+		{
+			SourceID:        1,
+			TargetID:        2,
+			RelationType:    models.RelationCauses,
+			Confidence:      0.8,
+			DetectionSource: models.DetectionSourceFileOverlap,
+			CreatedAt:       now.Format(time.RFC3339),
+			CreatedAtEpoch:  now.UnixMilli(),
+		},
+		{
+			SourceID:        2,
+			TargetID:        3,
+			RelationType:    models.RelationFixes,
+			Confidence:      0.9,
+			DetectionSource: models.DetectionSourceTemporalProximity,
+			CreatedAt:       now.Format(time.RFC3339),
+			CreatedAtEpoch:  now.UnixMilli(),
+		},
+	}
+
+	err := relationStore.StoreRelations(ctx, relations)
+	require.NoError(t, err)
+
+	count, err := relationStore.GetRelationCount(ctx, 2)
+	require.NoError(t, err)
+	assert.Equal(t, 2, count)
+
+	count, err = relationStore.GetRelationCount(ctx, 1)
+	require.NoError(t, err)
+	assert.Equal(t, 1, count)
+}
+
+func TestRelationStore_DeleteRelationsByObservationID(t *testing.T) {
+	relationStore, _, cleanup := testRelationStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+	now := time.Now()
+
+	relations := []*models.ObservationRelation{
+		{
+			SourceID:        1,
+			TargetID:        2,
+			RelationType:    models.RelationCauses,
+			Confidence:      0.8,
+			DetectionSource: models.DetectionSourceFileOverlap,
+			CreatedAt:       now.Format(time.RFC3339),
+			CreatedAtEpoch:  now.UnixMilli(),
+		},
+		{
+			SourceID:        2,
+			TargetID:        3,
+			RelationType:    models.RelationFixes,
+			Confidence:      0.9,
+			DetectionSource: models.DetectionSourceTemporalProximity,
+			CreatedAt:       now.Format(time.RFC3339),
+			CreatedAtEpoch:  now.UnixMilli(),
+		},
+		{
+			SourceID:        4,
+			TargetID:        5,
+			RelationType:    models.RelationRelatesTo,
+			Confidence:      0.7,
+			DetectionSource: models.DetectionSourceConceptOverlap,
+			CreatedAt:       now.Format(time.RFC3339),
+			CreatedAtEpoch:  now.UnixMilli(),
+		},
+	}
+
+	err := relationStore.StoreRelations(ctx, relations)
+	require.NoError(t, err)
+
+	// Delete relations involving observation 2
+	err = relationStore.DeleteRelationsByObservationID(ctx, 2)
+	require.NoError(t, err)
+
+	// Verify only 1 relation remains (4->5)
+	total, err := relationStore.GetTotalRelationCount(ctx)
+	require.NoError(t, err)
+	assert.Equal(t, 1, total)
+}

internal/db/gorm/scoring_store.go

@@ -0,0 +1,260 @@
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"context"
+	"time"
+
+	"gorm.io/gorm"
+
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+)
+
+// UpdateObservationFeedback updates the user feedback for an observation.
+// Feedback values: -1 (thumbs down), 0 (neutral), 1 (thumbs up).
+func (s *ObservationStore) UpdateObservationFeedback(ctx context.Context, id int64, feedback int) error {
+	now := time.Now().UnixMilli()
+
+	result := s.db.WithContext(ctx).
+		Model(&Observation{}).
+		Where("id = ?", id).
+		Updates(map[string]interface{}{
+			"user_feedback":          feedback,
+			"score_updated_at_epoch": now,
+		})
+
+	return result.Error
+}
+
+// IncrementRetrievalCount increments the retrieval counter for the given observation IDs.
+// This is called when observations are returned in search results.
+func (s *ObservationStore) IncrementRetrievalCount(ctx context.Context, ids []int64) error {
+	if len(ids) == 0 {
+		return nil
+	}
+
+	now := time.Now().UnixMilli()
+
+	// Use raw SQL for increment expression
+	result := s.db.WithContext(ctx).
+		Exec("UPDATE observations SET retrieval_count = COALESCE(retrieval_count, 0) + 1, last_retrieved_at_epoch = ? WHERE id IN ?",
+			now, ids)
+
+	return result.Error
+}
+
+// UpdateImportanceScore updates the importance score for a single observation.
+func (s *ObservationStore) UpdateImportanceScore(ctx context.Context, id int64, score float64) error {
+	now := time.Now().UnixMilli()
+
+	result := s.db.WithContext(ctx).
+		Model(&Observation{}).
+		Where("id = ?", id).
+		Updates(map[string]interface{}{
+			"importance_score":       score,
+			"score_updated_at_epoch": now,
+		})
+
+	return result.Error
+}
+
+// UpdateImportanceScores bulk updates importance scores for multiple observations.
+// This is more efficient than individual updates for batch recalculation.
+func (s *ObservationStore) UpdateImportanceScores(ctx context.Context, scores map[int64]float64) error {
+	if len(scores) == 0 {
+		return nil
+	}
+
+	return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		now := time.Now().UnixMilli()
+
+		for id, score := range scores {
+			err := tx.Model(&Observation{}).
+				Where("id = ?", id).
+				Updates(map[string]interface{}{
+					"importance_score":       score,
+					"score_updated_at_epoch": now,
+				}).Error
+
+			if err != nil {
+				return err
+			}
+		}
+
+		return nil
+	})
+}
+
+// GetObservationsNeedingScoreUpdate returns observations that need their importance score recalculated.
+// Returns observations where score_updated_at_epoch is NULL or older than the threshold.
+func (s *ObservationStore) GetObservationsNeedingScoreUpdate(ctx context.Context, threshold time.Duration, limit int) ([]*models.Observation, error) {
+	cutoff := time.Now().Add(-threshold).UnixMilli()
+
+	var observations []Observation
+
+	err := s.db.WithContext(ctx).
+		Where("score_updated_at_epoch IS NULL OR score_updated_at_epoch < ?", cutoff).
+		Order("created_at_epoch DESC").
+		Limit(limit).
+		Find(&observations).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelObservations(observations), nil
+}
+
+// GetConceptWeights returns all concept weights from the database.
+func (s *ObservationStore) GetConceptWeights(ctx context.Context) (map[string]float64, error) {
+	var weights []struct {
+		Concept string
+		Weight  float64
+	}
+
+	err := s.db.WithContext(ctx).
+		Table("concept_weights").
+		Select("concept, weight").
+		Scan(&weights).Error
+
+	if err != nil {
+		return models.DefaultConceptWeights, nil
+	}
+
+	if len(weights) == 0 {
+		return models.DefaultConceptWeights, nil
+	}
+
+	result := make(map[string]float64, len(weights))
+	for _, w := range weights {
+		result[w.Concept] = w.Weight
+	}
+
+	return result, nil
+}
+
+// SetConceptWeights stores concept weights in the database using UPSERT.
+func (s *ObservationStore) SetConceptWeights(ctx context.Context, weights map[string]float64) error {
+	if len(weights) == 0 {
+		return nil
+	}
+
+	return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		for concept, weight := range weights {
+			// UPSERT using raw SQL since GORM's ON CONFLICT is complex for this case
+			err := tx.Exec(`
+				INSERT INTO concept_weights (concept, weight, updated_at)
+				VALUES (?, ?, datetime('now'))
+				ON CONFLICT(concept) DO UPDATE SET weight = excluded.weight, updated_at = excluded.updated_at
+			`, concept, weight).Error
+
+			if err != nil {
+				return err
+			}
+		}
+
+		return nil
+	})
+}
+
+// UpdateConceptWeight updates a single concept weight in the database using UPSERT.
+func (s *ObservationStore) UpdateConceptWeight(ctx context.Context, concept string, weight float64) error {
+	return s.db.WithContext(ctx).Exec(`
+		INSERT INTO concept_weights (concept, weight, updated_at)
+		VALUES (?, ?, datetime('now'))
+		ON CONFLICT(concept) DO UPDATE SET weight = excluded.weight, updated_at = excluded.updated_at
+	`, concept, weight).Error
+}
+
+// FeedbackStats contains statistics about observation feedback and scoring.
+type FeedbackStats struct {
+	Total        int     `json:"total"`
+	Positive     int     `json:"positive"`
+	Negative     int     `json:"negative"`
+	Neutral      int     `json:"neutral"`
+	AvgScore     float64 `json:"avg_score"`
+	AvgRetrieval float64 `json:"avg_retrieval"`
+}
+
+// GetObservationFeedbackStats returns statistics about user feedback.
+func (s *ObservationStore) GetObservationFeedbackStats(ctx context.Context, project string) (*FeedbackStats, error) {
+	var stats FeedbackStats
+
+	query := s.db.WithContext(ctx).
+		Model(&Observation{}).
+		Select(`
+			COUNT(*) as total,
+			COALESCE(SUM(CASE WHEN user_feedback = 1 THEN 1 ELSE 0 END), 0) as positive,
+			COALESCE(SUM(CASE WHEN user_feedback = -1 THEN 1 ELSE 0 END), 0) as negative,
+			COALESCE(SUM(CASE WHEN user_feedback = 0 THEN 1 ELSE 0 END), 0) as neutral,
+			COALESCE(AVG(COALESCE(importance_score, 1.0)), 0) as avg_score,
+			COALESCE(AVG(COALESCE(retrieval_count, 0)), 0) as avg_retrieval
+		`)
+
+	if project != "" {
+		query = query.Where("project = ? OR scope = 'global'", project)
+	}
+
+	err := query.Scan(&stats).Error
+	if err != nil {
+		return nil, err
+	}
+
+	return &stats, nil
+}
+
+// GetTopScoringObservations returns the highest-scoring observations.
+func (s *ObservationStore) GetTopScoringObservations(ctx context.Context, project string, limit int) ([]*models.Observation, error) {
+	var observations []Observation
+
+	query := s.db.WithContext(ctx).
+		Order("COALESCE(importance_score, 1.0) DESC, created_at_epoch DESC").
+		Limit(limit)
+
+	if project != "" {
+		query = query.Where("project = ? OR scope = 'global'", project)
+	}
+
+	err := query.Find(&observations).Error
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelObservations(observations), nil
+}
+
+// GetMostRetrievedObservations returns the most frequently retrieved observations.
+func (s *ObservationStore) GetMostRetrievedObservations(ctx context.Context, project string, limit int) ([]*models.Observation, error) {
+	var observations []Observation
+
+	query := s.db.WithContext(ctx).
+		Where("retrieval_count > 0").
+		Order("retrieval_count DESC, created_at_epoch DESC").
+		Limit(limit)
+
+	if project != "" {
+		query = query.Where("project = ? OR scope = 'global'", project)
+	}
+
+	err := query.Find(&observations).Error
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelObservations(observations), nil
+}
+
+// ResetObservationScores resets all observation scores to their default values.
+// This is useful for testing or when changing the scoring algorithm.
+func (s *ObservationStore) ResetObservationScores(ctx context.Context) error {
+	// Use Where("1 = 1") to explicitly allow bulk update of all rows
+	result := s.db.WithContext(ctx).
+		Model(&Observation{}).
+		Where("1 = 1").
+		Updates(map[string]interface{}{
+			"importance_score":       1.0,
+			"score_updated_at_epoch": nil,
+		})
+
+	return result.Error
+}

internal/db/gorm/scoring_store_test.go

@@ -0,0 +1,355 @@
+//go:build fts5
+
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+)
+
+func TestObservationStore_UpdateImportanceScore(t *testing.T) {
+	obsStore, store, cleanup := testObservationStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	// Create observation
+	sessionStore := NewSessionStore(store)
+	sessionID, _ := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+	obs := &models.ParsedObservation{Type: models.ObsTypeDiscovery, Title: "Test"}
+	obsID, _, _ := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs, int(sessionID), 1)
+
+	// Update score
+	err := obsStore.UpdateImportanceScore(ctx, obsID, 5.0)
+	require.NoError(t, err)
+
+	// Verify
+	var dbObs Observation
+	store.DB.First(&dbObs, obsID)
+	assert.Equal(t, 5.0, dbObs.ImportanceScore)
+}
+
+func TestObservationStore_IncrementRetrievalCount(t *testing.T) {
+	obsStore, store, cleanup := testObservationStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	sessionStore := NewSessionStore(store)
+	sessionID, _ := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+	obs := &models.ParsedObservation{Type: models.ObsTypeDiscovery, Title: "Test"}
+	obsID, _, _ := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs, int(sessionID), 1)
+
+	err := obsStore.IncrementRetrievalCount(ctx, []int64{obsID})
+	require.NoError(t, err)
+
+	var dbObs Observation
+	store.DB.First(&dbObs, obsID)
+	assert.Equal(t, 1, dbObs.RetrievalCount)
+}
+
+func TestObservationStore_IncrementRetrievalCount_Multiple(t *testing.T) {
+	obsStore, store, cleanup := testObservationStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	sessionStore := NewSessionStore(store)
+	sessionID, _ := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+
+	// Create 3 observations
+	ids := make([]int64, 3)
+	for i := 0; i < 3; i++ {
+		obs := &models.ParsedObservation{Type: models.ObsTypeDiscovery, Title: "Test"}
+		obsID, _, _ := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs, int(sessionID), 1)
+		ids[i] = obsID
+	}
+
+	// Increment all
+	err := obsStore.IncrementRetrievalCount(ctx, ids)
+	require.NoError(t, err)
+
+	// Verify all were incremented
+	for _, id := range ids {
+		var dbObs Observation
+		store.DB.First(&dbObs, id)
+		assert.Equal(t, 1, dbObs.RetrievalCount)
+	}
+
+	// Increment again
+	err = obsStore.IncrementRetrievalCount(ctx, ids)
+	require.NoError(t, err)
+
+	// Verify all are now 2
+	for _, id := range ids {
+		var dbObs Observation
+		store.DB.First(&dbObs, id)
+		assert.Equal(t, 2, dbObs.RetrievalCount)
+	}
+}
+
+func TestObservationStore_UpdateImportanceScores_Bulk(t *testing.T) {
+	obsStore, store, cleanup := testObservationStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	sessionStore := NewSessionStore(store)
+	sessionID, _ := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+
+	// Create 3 observations
+	ids := make([]int64, 3)
+	for i := 0; i < 3; i++ {
+		obs := &models.ParsedObservation{Type: models.ObsTypeDiscovery, Title: "Test"}
+		obsID, _, _ := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs, int(sessionID), 1)
+		ids[i] = obsID
+	}
+
+	// Bulk update scores
+	scores := map[int64]float64{
+		ids[0]: 2.5,
+		ids[1]: 3.7,
+		ids[2]: 1.2,
+	}
+
+	err := obsStore.UpdateImportanceScores(ctx, scores)
+	require.NoError(t, err)
+
+	// Verify scores
+	for id, expectedScore := range scores {
+		var dbObs Observation
+		store.DB.First(&dbObs, id)
+		assert.Equal(t, expectedScore, dbObs.ImportanceScore)
+	}
+}
+
+func TestObservationStore_UpdateObservationFeedback(t *testing.T) {
+	obsStore, store, cleanup := testObservationStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	sessionStore := NewSessionStore(store)
+	sessionID, _ := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+	obs := &models.ParsedObservation{Type: models.ObsTypeDiscovery, Title: "Test"}
+	obsID, _, _ := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs, int(sessionID), 1)
+
+	// Set thumbs up
+	err := obsStore.UpdateObservationFeedback(ctx, obsID, 1)
+	require.NoError(t, err)
+
+	var dbObs Observation
+	store.DB.First(&dbObs, obsID)
+	assert.Equal(t, 1, dbObs.UserFeedback)
+
+	// Set thumbs down
+	err = obsStore.UpdateObservationFeedback(ctx, obsID, -1)
+	require.NoError(t, err)
+
+	store.DB.First(&dbObs, obsID)
+	assert.Equal(t, -1, dbObs.UserFeedback)
+}
+
+func TestObservationStore_GetObservationFeedbackStats(t *testing.T) {
+	obsStore, store, cleanup := testObservationStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	sessionStore := NewSessionStore(store)
+	sessionID, _ := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+
+	// Create observations with different feedback
+	obs1 := &models.ParsedObservation{Type: models.ObsTypeDiscovery, Title: "Test1"}
+	obsID1, _, _ := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs1, int(sessionID), 1)
+	obsStore.UpdateObservationFeedback(ctx, obsID1, 1) // thumbs up
+	obsStore.UpdateImportanceScore(ctx, obsID1, 3.0)
+
+	obs2 := &models.ParsedObservation{Type: models.ObsTypeBugfix, Title: "Test2"}
+	obsID2, _, _ := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs2, int(sessionID), 2)
+	obsStore.UpdateObservationFeedback(ctx, obsID2, -1) // thumbs down
+	obsStore.UpdateImportanceScore(ctx, obsID2, 2.0)
+
+	obs3 := &models.ParsedObservation{Type: models.ObsTypeFeature, Title: "Test3"}
+	obsID3, _, _ := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs3, int(sessionID), 3)
+	// neutral (0)
+	obsStore.UpdateImportanceScore(ctx, obsID3, 1.5)
+	obsStore.IncrementRetrievalCount(ctx, []int64{obsID1, obsID2, obsID3})
+
+	// Get stats
+	stats, err := obsStore.GetObservationFeedbackStats(ctx, "test-project")
+	require.NoError(t, err)
+
+	assert.Equal(t, 3, stats.Total)
+	assert.Equal(t, 1, stats.Positive)
+	assert.Equal(t, 1, stats.Negative)
+	assert.Equal(t, 1, stats.Neutral)
+	assert.InDelta(t, 2.166, stats.AvgScore, 0.01) // (3.0 + 2.0 + 1.5) / 3
+	assert.InDelta(t, 1.0, stats.AvgRetrieval, 0.01)
+}
+
+func TestObservationStore_GetTopScoringObservations(t *testing.T) {
+	obsStore, store, cleanup := testObservationStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	sessionStore := NewSessionStore(store)
+	sessionID, _ := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+
+	// Create observations with different scores
+	obs1 := &models.ParsedObservation{Type: models.ObsTypeDiscovery, Title: "High"}
+	obsID1, _, _ := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs1, int(sessionID), 1)
+	obsStore.UpdateImportanceScore(ctx, obsID1, 5.0)
+
+	obs2 := &models.ParsedObservation{Type: models.ObsTypeBugfix, Title: "Low"}
+	obsID2, _, _ := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs2, int(sessionID), 2)
+	obsStore.UpdateImportanceScore(ctx, obsID2, 1.0)
+
+	obs3 := &models.ParsedObservation{Type: models.ObsTypeFeature, Title: "Medium"}
+	obsID3, _, _ := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs3, int(sessionID), 3)
+	obsStore.UpdateImportanceScore(ctx, obsID3, 3.0)
+
+	// Get top 2
+	topObs, err := obsStore.GetTopScoringObservations(ctx, "test-project", 2)
+	require.NoError(t, err)
+
+	require.Len(t, topObs, 2)
+	assert.True(t, topObs[0].Title.Valid)
+	assert.Equal(t, "High", topObs[0].Title.String)
+	assert.Equal(t, 5.0, topObs[0].ImportanceScore)
+	assert.True(t, topObs[1].Title.Valid)
+	assert.Equal(t, "Medium", topObs[1].Title.String)
+	assert.Equal(t, 3.0, topObs[1].ImportanceScore)
+}
+
+func TestObservationStore_GetMostRetrievedObservations(t *testing.T) {
+	obsStore, store, cleanup := testObservationStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	sessionStore := NewSessionStore(store)
+	sessionID, _ := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+
+	// Create observations
+	obs1 := &models.ParsedObservation{Type: models.ObsTypeDiscovery, Title: "Popular"}
+	obsID1, _, _ := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs1, int(sessionID), 1)
+
+	obs2 := &models.ParsedObservation{Type: models.ObsTypeBugfix, Title: "Unpopular"}
+	obsID2, _, _ := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs2, int(sessionID), 2)
+
+	// Increment retrieval counts - each call increments by 1
+	obsStore.IncrementRetrievalCount(ctx, []int64{obsID1}) // increment by 1
+	obsStore.IncrementRetrievalCount(ctx, []int64{obsID1}) // increment by 1 again (total: 2)
+	obsStore.IncrementRetrievalCount(ctx, []int64{obsID1}) // increment by 1 again (total: 3)
+	obsStore.IncrementRetrievalCount(ctx, []int64{obsID2}) // increment by 1 (total: 1)
+
+	// Get most retrieved - should return obsID1 (Popular) with count 3
+	topObs, err := obsStore.GetMostRetrievedObservations(ctx, "test-project", 2)
+	require.NoError(t, err)
+
+	require.Len(t, topObs, 2)
+	assert.True(t, topObs[0].Title.Valid)
+	assert.Equal(t, "Popular", topObs[0].Title.String)
+	assert.Equal(t, 3, topObs[0].RetrievalCount)
+	assert.True(t, topObs[1].Title.Valid)
+	assert.Equal(t, "Unpopular", topObs[1].Title.String)
+	assert.Equal(t, 1, topObs[1].RetrievalCount)
+}
+
+func TestObservationStore_SetConceptWeights(t *testing.T) {
+	obsStore, _, cleanup := testObservationStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	// Set weights
+	weights := map[string]float64{
+		"security":      2.0,
+		"performance":   1.5,
+		"best-practice": 1.8,
+	}
+
+	err := obsStore.SetConceptWeights(ctx, weights)
+	require.NoError(t, err)
+
+	// Get weights back
+	retrieved, err := obsStore.GetConceptWeights(ctx)
+	require.NoError(t, err)
+
+	assert.Equal(t, 2.0, retrieved["security"])
+	assert.Equal(t, 1.5, retrieved["performance"])
+	assert.Equal(t, 1.8, retrieved["best-practice"])
+
+	// Update weights (UPSERT)
+	weights["security"] = 2.5
+	weights["scalability"] = 1.2
+
+	err = obsStore.SetConceptWeights(ctx, weights)
+	require.NoError(t, err)
+
+	retrieved, err = obsStore.GetConceptWeights(ctx)
+	require.NoError(t, err)
+
+	assert.Equal(t, 2.5, retrieved["security"])      // updated
+	assert.Equal(t, 1.5, retrieved["performance"])   // unchanged
+	assert.Equal(t, 1.2, retrieved["scalability"])   // new
+	assert.Equal(t, 1.8, retrieved["best-practice"]) // unchanged
+}
+
+func TestObservationStore_GetObservationsNeedingScoreUpdate(t *testing.T) {
+	obsStore, store, cleanup := testObservationStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	sessionStore := NewSessionStore(store)
+	sessionID, _ := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+
+	// Create observation with no score update
+	obs1 := &models.ParsedObservation{Type: models.ObsTypeDiscovery, Title: "Needs Update"}
+	obsID1, _, _ := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs1, int(sessionID), 1)
+
+	// Create observation with recent score update
+	obs2 := &models.ParsedObservation{Type: models.ObsTypeBugfix, Title: "Recently Updated"}
+	obsID2, _, _ := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs2, int(sessionID), 2)
+	obsStore.UpdateImportanceScore(ctx, obsID2, 2.0)
+
+	// Get observations needing update (within 1 hour threshold)
+	needsUpdate, err := obsStore.GetObservationsNeedingScoreUpdate(ctx, 1*time.Hour, 10)
+	require.NoError(t, err)
+
+	// Only obs1 should need update (obs2 was just updated)
+	assert.Len(t, needsUpdate, 1)
+	assert.Equal(t, obsID1, needsUpdate[0].ID)
+	assert.True(t, needsUpdate[0].Title.Valid)
+	assert.Equal(t, "Needs Update", needsUpdate[0].Title.String)
+}
+
+func TestObservationStore_ResetObservationScores(t *testing.T) {
+	obsStore, store, cleanup := testObservationStore(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	sessionStore := NewSessionStore(store)
+	sessionID, _ := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+
+	// Create observations with custom scores
+	obs1 := &models.ParsedObservation{Type: models.ObsTypeDiscovery, Title: "Test1"}
+	obsID1, _, _ := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs1, int(sessionID), 1)
+	obsStore.UpdateImportanceScore(ctx, obsID1, 5.0)
+
+	obs2 := &models.ParsedObservation{Type: models.ObsTypeBugfix, Title: "Test2"}
+	obsID2, _, _ := obsStore.StoreObservation(ctx, "claude-1", "test-project", obs2, int(sessionID), 2)
+	obsStore.UpdateImportanceScore(ctx, obsID2, 3.0)
+
+	// Reset all scores
+	err := obsStore.ResetObservationScores(ctx)
+	require.NoError(t, err)
+
+	// Verify all scores are 1.0
+	var dbObs1, dbObs2 Observation
+	store.DB.First(&dbObs1, obsID1)
+	store.DB.First(&dbObs2, obsID2)
+
+	assert.Equal(t, 1.0, dbObs1.ImportanceScore)
+	assert.Equal(t, 1.0, dbObs2.ImportanceScore)
+}

internal/db/gorm/session_store.go

@@ -0,0 +1,198 @@
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"context"
+	"database/sql"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+)
+
+// SessionStore provides session-related database operations using GORM.
+type SessionStore struct {
+	db *gorm.DB
+}
+
+// NewSessionStore creates a new session store.
+func NewSessionStore(store *Store) *SessionStore {
+	return &SessionStore{db: store.DB}
+}
+
+// CreateSDKSession creates a new SDK session (idempotent - returns existing ID if exists).
+// This is the KEY to how claude-mnemonic stays unified across hooks.
+func (s *SessionStore) CreateSDKSession(ctx context.Context, claudeSessionID, project, userPrompt string) (int64, error) {
+	now := time.Now()
+
+	session := &SDKSession{
+		ClaudeSessionID: claudeSessionID,
+		SDKSessionID: func() sql.NullString {
+			return sql.NullString{String: claudeSessionID, Valid: true}
+		}(),
+		Project: project,
+		UserPrompt: func() sql.NullString {
+			if userPrompt != "" {
+				return sql.NullString{String: userPrompt, Valid: true}
+			}
+			return sql.NullString{Valid: false}
+		}(),
+		Status:         "active",
+		StartedAt:      now.Format(time.RFC3339),
+		StartedAtEpoch: now.UnixMilli(),
+	}
+
+	// CRITICAL: INSERT OR IGNORE makes this idempotent
+	// Use OnConflict with DoNothing to achieve INSERT OR IGNORE behavior
+	result := s.db.WithContext(ctx).
+		Clauses(clause.OnConflict{
+			Columns:   []clause.Column{{Name: "claude_session_id"}},
+			DoNothing: true,
+		}).
+		Create(session)
+
+	if result.Error != nil {
+		return 0, result.Error
+	}
+
+	// Check if insert happened
+	if result.RowsAffected == 0 {
+		// Session exists - UPDATE project and user_prompt if we have non-empty values
+		if project != "" {
+			updates := map[string]interface{}{
+				"project": project,
+			}
+			if userPrompt != "" {
+				updates["user_prompt"] = userPrompt
+			}
+			s.db.WithContext(ctx).
+				Model(&SDKSession{}).
+				Where("claude_session_id = ?", claudeSessionID).
+				Updates(updates)
+		}
+
+		// Fetch existing session
+		var existing SDKSession
+		err := s.db.WithContext(ctx).
+			Where("claude_session_id = ?", claudeSessionID).
+			First(&existing).Error
+		if err != nil {
+			return 0, err
+		}
+		return existing.ID, nil
+	}
+
+	return session.ID, nil
+}
+
+// GetSessionByID retrieves a session by its database ID.
+func (s *SessionStore) GetSessionByID(ctx context.Context, id int64) (*models.SDKSession, error) {
+	var sess SDKSession
+	err := s.db.WithContext(ctx).First(&sess, id).Error
+	if err == gorm.ErrRecordNotFound {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return toModelSDKSession(&sess), nil
+}
+
+// FindAnySDKSession finds any session by Claude session ID (any status).
+func (s *SessionStore) FindAnySDKSession(ctx context.Context, claudeSessionID string) (*models.SDKSession, error) {
+	var sess SDKSession
+	err := s.db.WithContext(ctx).
+		Where("claude_session_id = ?", claudeSessionID).
+		First(&sess).Error
+	if err == gorm.ErrRecordNotFound {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return toModelSDKSession(&sess), nil
+}
+
+// IncrementPromptCounter increments the prompt counter and returns the new value.
+func (s *SessionStore) IncrementPromptCounter(ctx context.Context, id int64) (int, error) {
+	// Atomic increment using GORM expression
+	err := s.db.WithContext(ctx).
+		Model(&SDKSession{}).
+		Where("id = ?", id).
+		Update("prompt_counter", gorm.Expr("COALESCE(prompt_counter, 0) + 1")).Error
+	if err != nil {
+		return 0, err
+	}
+
+	// Fetch updated value
+	var sess SDKSession
+	err = s.db.WithContext(ctx).
+		Select("prompt_counter").
+		First(&sess, id).Error
+	if err != nil {
+		return 0, err
+	}
+
+	return sess.PromptCounter, nil
+}
+
+// GetPromptCounter returns the current prompt counter for a session.
+func (s *SessionStore) GetPromptCounter(ctx context.Context, id int64) (int, error) {
+	var sess SDKSession
+	err := s.db.WithContext(ctx).
+		Select("prompt_counter").
+		First(&sess, id).Error
+	if err != nil {
+		return 0, err
+	}
+	return sess.PromptCounter, nil
+}
+
+// GetSessionsToday returns the count of sessions started today.
+func (s *SessionStore) GetSessionsToday(ctx context.Context) (int, error) {
+	// Get start of today in milliseconds
+	now := time.Now()
+	startOfDay := time.Date(now.Year(), now.Month(), now.Day(), 0, 0, 0, 0, now.Location())
+	startEpoch := startOfDay.UnixMilli()
+
+	var count int64
+	err := s.db.WithContext(ctx).
+		Model(&SDKSession{}).
+		Where("started_at_epoch >= ?", startEpoch).
+		Count(&count).Error
+
+	return int(count), err
+}
+
+// GetAllProjects returns all unique project names.
+func (s *SessionStore) GetAllProjects(ctx context.Context) ([]string, error) {
+	var projects []string
+	err := s.db.WithContext(ctx).
+		Model(&SDKSession{}).
+		Distinct("project").
+		Where("project IS NOT NULL AND project != ''").
+		Order("project ASC").
+		Pluck("project", &projects).Error
+
+	return projects, err
+}
+
+// toModelSDKSession converts a GORM SDKSession to pkg/models.SDKSession.
+func toModelSDKSession(sess *SDKSession) *models.SDKSession {
+	return &models.SDKSession{
+		ID:               sess.ID,
+		ClaudeSessionID:  sess.ClaudeSessionID,
+		SDKSessionID:     sess.SDKSessionID,
+		Project:          sess.Project,
+		UserPrompt:       sess.UserPrompt,
+		WorkerPort:       sess.WorkerPort,
+		PromptCounter:    int64(sess.PromptCounter),
+		Status:           models.SessionStatus(sess.Status),
+		StartedAt:        sess.StartedAt,
+		StartedAtEpoch:   sess.StartedAtEpoch,
+		CompletedAt:      sess.CompletedAt,
+		CompletedAtEpoch: sess.CompletedAtEpoch,
+	}
+}

internal/db/gorm/session_store_test.go

@@ -0,0 +1,259 @@
+//go:build fts5
+
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm/logger"
+
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+)
+
+// testSessionStore creates a SessionStore with a temporary database for testing.
+func testSessionStore(t *testing.T) (*SessionStore, *Store, func()) {
+	t.Helper()
+
+	tmpDir, err := os.MkdirTemp("", "gorm_session_test_*")
+	if err != nil {
+		t.Fatalf("create temp dir: %v", err)
+	}
+
+	dbPath := filepath.Join(tmpDir, "test.db")
+	cfg := Config{
+		Path:     dbPath,
+		MaxConns: 4,
+		LogLevel: logger.Silent,
+	}
+
+	store, err := NewStore(cfg)
+	if err != nil {
+		os.RemoveAll(tmpDir)
+		t.Fatalf("NewStore failed: %v", err)
+	}
+
+	sessionStore := NewSessionStore(store)
+
+	cleanup := func() {
+		store.Close()
+		os.RemoveAll(tmpDir)
+	}
+
+	return sessionStore, store, cleanup
+}
+
+func TestSessionStore_CreateSDKSession(t *testing.T) {
+	sessionStore, _, cleanup := testSessionStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create a new session
+	id, err := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "initial prompt")
+	require.NoError(t, err)
+	assert.Greater(t, id, int64(0))
+
+	// Retrieve and verify
+	sess, err := sessionStore.GetSessionByID(ctx, id)
+	require.NoError(t, err)
+	require.NotNil(t, sess)
+	assert.Equal(t, "claude-1", sess.ClaudeSessionID)
+	assert.Equal(t, "test-project", sess.Project)
+	assert.Equal(t, models.SessionStatusActive, sess.Status)
+	assert.True(t, sess.UserPrompt.Valid)
+	assert.Equal(t, "initial prompt", sess.UserPrompt.String)
+}
+
+func TestSessionStore_CreateSDKSession_Idempotent(t *testing.T) {
+	sessionStore, _, cleanup := testSessionStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create first session
+	id1, err := sessionStore.CreateSDKSession(ctx, "claude-1", "project-a", "prompt 1")
+	require.NoError(t, err)
+
+	// Create again with same claude_session_id but different project
+	id2, err := sessionStore.CreateSDKSession(ctx, "claude-1", "project-b", "prompt 2")
+	require.NoError(t, err)
+
+	// Should return same ID (idempotent)
+	assert.Equal(t, id1, id2)
+
+	// Should have updated project to project-b
+	sess, err := sessionStore.GetSessionByID(ctx, id1)
+	require.NoError(t, err)
+	assert.Equal(t, "project-b", sess.Project)
+	assert.Equal(t, "prompt 2", sess.UserPrompt.String)
+}
+
+func TestSessionStore_CreateSDKSession_EmptyPrompt(t *testing.T) {
+	sessionStore, _, cleanup := testSessionStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create session with empty prompt
+	id, err := sessionStore.CreateSDKSession(ctx, "claude-2", "test-project", "")
+	require.NoError(t, err)
+	assert.Greater(t, id, int64(0))
+
+	// Verify prompt is NULL
+	sess, err := sessionStore.GetSessionByID(ctx, id)
+	require.NoError(t, err)
+	assert.False(t, sess.UserPrompt.Valid)
+}
+
+func TestSessionStore_FindAnySDKSession(t *testing.T) {
+	sessionStore, _, cleanup := testSessionStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create a session
+	_, err := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+	require.NoError(t, err)
+
+	// Find it
+	sess, err := sessionStore.FindAnySDKSession(ctx, "claude-1")
+	require.NoError(t, err)
+	require.NotNil(t, sess)
+	assert.Equal(t, "claude-1", sess.ClaudeSessionID)
+
+	// Try to find non-existent
+	sess, err = sessionStore.FindAnySDKSession(ctx, "claude-nonexistent")
+	require.NoError(t, err)
+	assert.Nil(t, sess)
+}
+
+func TestSessionStore_GetSessionByID_NotFound(t *testing.T) {
+	sessionStore, _, cleanup := testSessionStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Try to get non-existent session
+	sess, err := sessionStore.GetSessionByID(ctx, 99999)
+	require.NoError(t, err)
+	assert.Nil(t, sess)
+}
+
+func TestSessionStore_IncrementPromptCounter(t *testing.T) {
+	sessionStore, _, cleanup := testSessionStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create a session
+	id, err := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+	require.NoError(t, err)
+
+	// Initial counter should be 0
+	counter, err := sessionStore.GetPromptCounter(ctx, id)
+	require.NoError(t, err)
+	assert.Equal(t, 0, counter)
+
+	// Increment
+	counter, err = sessionStore.IncrementPromptCounter(ctx, id)
+	require.NoError(t, err)
+	assert.Equal(t, 1, counter)
+
+	// Increment again
+	counter, err = sessionStore.IncrementPromptCounter(ctx, id)
+	require.NoError(t, err)
+	assert.Equal(t, 2, counter)
+
+	// Verify via GetPromptCounter
+	counter, err = sessionStore.GetPromptCounter(ctx, id)
+	require.NoError(t, err)
+	assert.Equal(t, 2, counter)
+}
+
+func TestSessionStore_GetSessionsToday(t *testing.T) {
+	sessionStore, _, cleanup := testSessionStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Initially should be 0
+	count, err := sessionStore.GetSessionsToday(ctx)
+	require.NoError(t, err)
+	assert.Equal(t, 0, count)
+
+	// Create some sessions
+	_, err = sessionStore.CreateSDKSession(ctx, "claude-1", "project-1", "")
+	require.NoError(t, err)
+
+	_, err = sessionStore.CreateSDKSession(ctx, "claude-2", "project-2", "")
+	require.NoError(t, err)
+
+	// Should now have 2 sessions today
+	count, err = sessionStore.GetSessionsToday(ctx)
+	require.NoError(t, err)
+	assert.Equal(t, 2, count)
+}
+
+func TestSessionStore_GetAllProjects(t *testing.T) {
+	sessionStore, _, cleanup := testSessionStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Initially should be empty
+	projects, err := sessionStore.GetAllProjects(ctx)
+	require.NoError(t, err)
+	assert.Empty(t, projects)
+
+	// Create sessions with different projects
+	_, err = sessionStore.CreateSDKSession(ctx, "claude-1", "project-a", "")
+	require.NoError(t, err)
+
+	_, err = sessionStore.CreateSDKSession(ctx, "claude-2", "project-b", "")
+	require.NoError(t, err)
+
+	_, err = sessionStore.CreateSDKSession(ctx, "claude-3", "project-a", "") // Duplicate project
+	require.NoError(t, err)
+
+	// Should get distinct projects in alphabetical order
+	projects, err = sessionStore.GetAllProjects(ctx)
+	require.NoError(t, err)
+	assert.Equal(t, []string{"project-a", "project-b"}, projects)
+}
+
+func TestSessionStore_SessionFields(t *testing.T) {
+	sessionStore, _, cleanup := testSessionStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create a session
+	id, err := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "test prompt")
+	require.NoError(t, err)
+
+	// Retrieve and verify all fields
+	sess, err := sessionStore.GetSessionByID(ctx, id)
+	require.NoError(t, err)
+	require.NotNil(t, sess)
+
+	// Verify all fields
+	assert.Equal(t, id, sess.ID)
+	assert.Equal(t, "claude-1", sess.ClaudeSessionID)
+	assert.True(t, sess.SDKSessionID.Valid)
+	assert.Equal(t, "claude-1", sess.SDKSessionID.String) // Should be same as ClaudeSessionID
+	assert.Equal(t, "test-project", sess.Project)
+	assert.True(t, sess.UserPrompt.Valid)
+	assert.Equal(t, "test prompt", sess.UserPrompt.String)
+	assert.Equal(t, int64(0), sess.PromptCounter)
+	assert.Equal(t, models.SessionStatusActive, sess.Status)
+	assert.NotEmpty(t, sess.StartedAt)
+	assert.Greater(t, sess.StartedAtEpoch, int64(0))
+	assert.False(t, sess.CompletedAt.Valid)      // Should be NULL
+	assert.False(t, sess.CompletedAtEpoch.Valid) // Should be NULL
+}

internal/db/gorm/sqlite_build.go

@@ -0,0 +1,8 @@
+//go:build !sqlite_omit_load_extension
+// +build !sqlite_omit_load_extension
+
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+// This file ensures mattn/go-sqlite3 is built with FTS5 and other extensions enabled.
+// The build tag ensures extensions are not omitted.

internal/db/gorm/store.go

@@ -0,0 +1,117 @@
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"database/sql"
+	"fmt"
+
+	sqlite_vec "github.com/asg017/sqlite-vec-go-bindings/cgo"
+	_ "github.com/mattn/go-sqlite3" // Import SQLite driver with FTS5 support
+	"gorm.io/driver/sqlite"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+// Store represents the GORM database connection with sqlite-vec support.
+type Store struct {
+	DB    *gorm.DB
+	sqlDB *sql.DB // For FTS5 and sqlite-vec operations that require raw SQL
+}
+
+// Config holds database configuration.
+type Config struct {
+	Path     string          // Path to SQLite database file
+	MaxConns int             // Maximum number of open connections (default: 4)
+	LogLevel logger.LogLevel // GORM log level (logger.Silent for production)
+}
+
+// NewStore creates a new Store with WAL mode enabled and sqlite-vec registered.
+// CRITICAL: WAL mode and foreign keys are enabled via pragmas for concurrent reads.
+func NewStore(cfg Config) (*Store, error) {
+	// 1. Register sqlite-vec extension (must be done before opening database)
+	sqlite_vec.Auto()
+
+	// 2. Build connection string (foreign keys enabled in DSN)
+	// Use sqlite3 driver (mattn/go-sqlite3) which has FTS5 support
+	dsn := cfg.Path + "?_foreign_keys=ON"
+
+	// 3. Open raw database connection with mattn/go-sqlite3 (has FTS5 support)
+	sqlDB, err := sql.Open("sqlite3", dsn)
+	if err != nil {
+		return nil, fmt.Errorf("open database: %w", err)
+	}
+
+	// 4. Wrap with GORM using existing connection
+	db, err := gorm.Open(sqlite.Dialector{
+		Conn: sqlDB,
+	}, &gorm.Config{
+		Logger: logger.Default.LogMode(cfg.LogLevel),
+		// PrepareStmt enables prepared statement caching for performance
+		PrepareStmt: true,
+		// Disable default timestamp fields (we manage created_at manually)
+		NowFunc: nil,
+	})
+	if err != nil {
+		_ = sqlDB.Close() // Explicitly ignore close error during cleanup
+		return nil, fmt.Errorf("open gorm: %w", err)
+	}
+
+	// 5. Configure connection pool (same settings as current implementation)
+	maxConns := cfg.MaxConns
+	if maxConns <= 0 {
+		maxConns = 4
+	}
+	sqlDB.SetMaxOpenConns(maxConns)
+	sqlDB.SetMaxIdleConns(maxConns)
+	sqlDB.SetConnMaxLifetime(0) // Never expire (SQLite connections are cheap)
+
+	// 6. Verify connection
+	if err := sqlDB.Ping(); err != nil {
+		return nil, fmt.Errorf("ping database: %w", err)
+	}
+
+	store := &Store{
+		DB:    db,
+		sqlDB: sqlDB,
+	}
+
+	// 7. Run migrations FIRST (before PRAGMA commands)
+	if err := runMigrations(db, sqlDB); err != nil {
+		return nil, fmt.Errorf("run migrations: %w", err)
+	}
+
+	// 8. CRITICAL: Set WAL mode and synchronous mode via raw SQL
+	// Use raw sqlDB to avoid GORM transaction issues
+	if _, err := sqlDB.Exec("PRAGMA journal_mode=WAL"); err != nil {
+		return nil, fmt.Errorf("set WAL mode: %w", err)
+	}
+	if _, err := sqlDB.Exec("PRAGMA synchronous=NORMAL"); err != nil {
+		return nil, fmt.Errorf("set synchronous mode: %w", err)
+	}
+
+	return store, nil
+}
+
+// Close closes the database connection.
+func (s *Store) Close() error {
+	return s.sqlDB.Close()
+}
+
+// Ping verifies the database connection is alive.
+func (s *Store) Ping() error {
+	return s.sqlDB.Ping()
+}
+
+// GetRawDB returns the underlying *sql.DB for operations GORM can't handle.
+// Use this for:
+// - FTS5 full-text search queries (MATCH operator)
+// - sqlite-vec vector operations
+// - Complex raw SQL queries
+func (s *Store) GetRawDB() *sql.DB {
+	return s.sqlDB
+}
+
+// GetDB returns the GORM DB instance for standard queries.
+func (s *Store) GetDB() *gorm.DB {
+	return s.DB
+}

internal/db/gorm/store_test.go

@@ -0,0 +1,152 @@
+//go:build fts5
+
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"gorm.io/gorm/logger"
+)
+
+func TestNewStore(t *testing.T) {
+	// Create temporary directory for test database
+	tmpDir, err := os.MkdirTemp("", "gorm_test_*")
+	if err != nil {
+		t.Fatalf("create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	dbPath := filepath.Join(tmpDir, "test.db")
+
+	// Create store with migrations
+	cfg := Config{
+		Path:     dbPath,
+		MaxConns: 4,
+		LogLevel: logger.Silent,
+	}
+
+	store, err := NewStore(cfg)
+	if err != nil {
+		t.Fatalf("NewStore failed: %v", err)
+	}
+	defer store.Close()
+
+	// Verify connection works
+	sqlDB := store.GetRawDB()
+	if err := sqlDB.Ping(); err != nil {
+		t.Fatalf("ping failed: %v", err)
+	}
+
+	// Verify WAL mode is enabled
+	var journalMode string
+	err = store.DB.Raw("PRAGMA journal_mode").Scan(&journalMode).Error
+	if err != nil {
+		t.Fatalf("query journal_mode failed: %v", err)
+	}
+	if journalMode != "wal" {
+		t.Errorf("expected WAL mode, got %q", journalMode)
+	}
+
+	// Verify core tables exist
+	tables := []string{
+		"sdk_sessions",
+		"observations",
+		"session_summaries",
+		"user_prompts",
+		"observation_conflicts",
+		"observation_relations",
+		"patterns",
+		"concept_weights",
+	}
+
+	for _, table := range tables {
+		exists := store.DB.Migrator().HasTable(table)
+		if !exists {
+			t.Errorf("table %q does not exist", table)
+		}
+	}
+
+	// Verify FTS5 virtual tables exist (cannot use Migrator().HasTable for virtual tables)
+	ftsTables := []string{
+		"user_prompts_fts",
+		"observations_fts",
+		"session_summaries_fts",
+		"patterns_fts",
+	}
+
+	for _, table := range ftsTables {
+		var count int
+		err := store.DB.Raw("SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name=?", table).Scan(&count).Error
+		if err != nil {
+			t.Errorf("check FTS table %q failed: %v", table, err)
+		}
+		if count != 1 {
+			t.Errorf("FTS table %q does not exist", table)
+		}
+	}
+
+	// Verify vectors table exists (virtual table)
+	var vectorsCount int
+	err = store.DB.Raw("SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name='vectors'").Scan(&vectorsCount).Error
+	if err != nil {
+		t.Errorf("check vectors table failed: %v", err)
+	}
+	if vectorsCount != 1 {
+		t.Errorf("vectors table does not exist")
+	}
+
+	// Verify concept_weights seed data exists
+	var conceptCount int64
+	store.DB.Model(&ConceptWeight{}).Count(&conceptCount)
+	if conceptCount != 12 {
+		t.Errorf("expected 12 concept weights, got %d", conceptCount)
+	}
+
+	t.Logf("✅ Phase 1 Foundation: All migrations successful")
+	t.Logf("   - Core tables: %d", len(tables))
+	t.Logf("   - FTS5 tables: %d", len(ftsTables))
+	t.Logf("   - Vector table: 1")
+	t.Logf("   - Seed data: %d concept weights", conceptCount)
+}
+
+func TestMigrationIdempotency(t *testing.T) {
+	// Create temporary directory for test database
+	tmpDir, err := os.MkdirTemp("", "gorm_idempotency_*")
+	if err != nil {
+		t.Fatalf("create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	dbPath := filepath.Join(tmpDir, "test.db")
+	cfg := Config{
+		Path:     dbPath,
+		MaxConns: 4,
+		LogLevel: logger.Silent,
+	}
+
+	// Run migrations first time
+	store1, err := NewStore(cfg)
+	if err != nil {
+		t.Fatalf("NewStore (first) failed: %v", err)
+	}
+	store1.Close()
+
+	// Run migrations second time (should be idempotent)
+	store2, err := NewStore(cfg)
+	if err != nil {
+		t.Fatalf("NewStore (second) failed: %v", err)
+	}
+	defer store2.Close()
+
+	// Verify concept_weights seed data is still exactly 12 (INSERT OR IGNORE)
+	var conceptCount int64
+	store2.DB.Model(&ConceptWeight{}).Count(&conceptCount)
+	if conceptCount != 12 {
+		t.Errorf("expected 12 concept weights after second migration, got %d", conceptCount)
+	}
+
+	t.Logf("✅ Migrations are idempotent")
+}

internal/db/gorm/summary_store.go

@@ -0,0 +1,171 @@
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"context"
+	"database/sql"
+	"time"
+
+	"gorm.io/gorm"
+
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+)
+
+// SummaryStore provides summary-related database operations using GORM.
+type SummaryStore struct {
+	db *gorm.DB
+}
+
+// NewSummaryStore creates a new summary store.
+func NewSummaryStore(store *Store) *SummaryStore {
+	return &SummaryStore{db: store.DB}
+}
+
+// StoreSummary stores a new session summary.
+func (s *SummaryStore) StoreSummary(ctx context.Context, sdkSessionID, project string, summary *models.ParsedSummary, promptNumber int, discoveryTokens int64) (int64, int64, error) {
+	now := time.Now()
+	nowEpoch := now.UnixMilli()
+
+	// Ensure session exists (auto-create if missing)
+	if err := EnsureSessionExists(ctx, s.db, sdkSessionID, project); err != nil {
+		return 0, 0, err
+	}
+
+	dbSummary := &SessionSummary{
+		SDKSessionID: sdkSessionID,
+		Project:      project,
+		Request:      nullString(summary.Request),
+		Investigated: nullString(summary.Investigated),
+		Learned:      nullString(summary.Learned),
+		Completed:    nullString(summary.Completed),
+		NextSteps:    nullString(summary.NextSteps),
+		Notes:        nullString(summary.Notes),
+		PromptNumber: func() sql.NullInt64 {
+			if promptNumber > 0 {
+				return sql.NullInt64{Int64: int64(promptNumber), Valid: true}
+			}
+			return sql.NullInt64{Valid: false}
+		}(),
+		DiscoveryTokens: discoveryTokens,
+		CreatedAt:       now.Format(time.RFC3339),
+		CreatedAtEpoch:  nowEpoch,
+	}
+
+	err := s.db.WithContext(ctx).Create(dbSummary).Error
+	if err != nil {
+		return 0, 0, err
+	}
+
+	return dbSummary.ID, nowEpoch, nil
+}
+
+// GetSummariesByIDs retrieves summaries by a list of IDs.
+func (s *SummaryStore) GetSummariesByIDs(ctx context.Context, ids []int64, orderBy string, limit int) ([]*models.SessionSummary, error) {
+	if len(ids) == 0 {
+		return nil, nil
+	}
+
+	var dbSummaries []SessionSummary
+	query := s.db.WithContext(ctx).Where("id IN ?", ids)
+
+	// Apply ordering
+	switch orderBy {
+	case "date_asc":
+		query = query.Order("created_at_epoch ASC")
+	case "date_desc", "default", "":
+		query = query.Order("created_at_epoch DESC")
+	}
+
+	// Apply limit
+	if limit > 0 {
+		query = query.Limit(limit)
+	}
+
+	err := query.Find(&dbSummaries).Error
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelSessionSummaries(dbSummaries), nil
+}
+
+// GetRecentSummaries retrieves recent summaries for a project.
+func (s *SummaryStore) GetRecentSummaries(ctx context.Context, project string, limit int) ([]*models.SessionSummary, error) {
+	var dbSummaries []SessionSummary
+	err := s.db.WithContext(ctx).
+		Where("project = ?", project).
+		Order("created_at_epoch DESC").
+		Limit(limit).
+		Find(&dbSummaries).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelSessionSummaries(dbSummaries), nil
+}
+
+// GetAllRecentSummaries retrieves recent summaries across all projects.
+func (s *SummaryStore) GetAllRecentSummaries(ctx context.Context, limit int) ([]*models.SessionSummary, error) {
+	var dbSummaries []SessionSummary
+	err := s.db.WithContext(ctx).
+		Order("created_at_epoch DESC").
+		Limit(limit).
+		Find(&dbSummaries).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelSessionSummaries(dbSummaries), nil
+}
+
+// GetAllSummaries retrieves all summaries (for vector rebuild).
+func (s *SummaryStore) GetAllSummaries(ctx context.Context) ([]*models.SessionSummary, error) {
+	var dbSummaries []SessionSummary
+	err := s.db.WithContext(ctx).
+		Order("id").
+		Find(&dbSummaries).Error
+
+	if err != nil {
+		return nil, err
+	}
+
+	return toModelSessionSummaries(dbSummaries), nil
+}
+
+// toModelSessionSummary converts a GORM SessionSummary to pkg/models.SessionSummary.
+func toModelSessionSummary(s *SessionSummary) *models.SessionSummary {
+	return &models.SessionSummary{
+		ID:              s.ID,
+		SDKSessionID:    s.SDKSessionID,
+		Project:         s.Project,
+		Request:         s.Request,
+		Investigated:    s.Investigated,
+		Learned:         s.Learned,
+		Completed:       s.Completed,
+		NextSteps:       s.NextSteps,
+		Notes:           s.Notes,
+		PromptNumber:    s.PromptNumber,
+		DiscoveryTokens: s.DiscoveryTokens,
+		CreatedAt:       s.CreatedAt,
+		CreatedAtEpoch:  s.CreatedAtEpoch,
+	}
+}
+
+// toModelSessionSummaries converts a slice of GORM SessionSummary to pkg/models.SessionSummary.
+func toModelSessionSummaries(summaries []SessionSummary) []*models.SessionSummary {
+	result := make([]*models.SessionSummary, len(summaries))
+	for i := range summaries {
+		result[i] = toModelSessionSummary(&summaries[i])
+	}
+	return result
+}
+
+// nullString converts a string to sql.NullString.
+func nullString(s string) sql.NullString {
+	if s == "" {
+		return sql.NullString{Valid: false}
+	}
+	return sql.NullString{String: s, Valid: true}
+}

internal/db/gorm/summary_store_test.go

@@ -0,0 +1,278 @@
+//go:build fts5
+
+// Package gorm provides GORM-based database operations for claude-mnemonic.
+package gorm
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm/logger"
+
+	"github.com/lukaszraczylo/claude-mnemonic/pkg/models"
+)
+
+// testSummaryStore creates a SummaryStore with a temporary database for testing.
+func testSummaryStore(t *testing.T) (*SummaryStore, *Store, func()) {
+	t.Helper()
+
+	tmpDir, err := os.MkdirTemp("", "gorm_summary_test_*")
+	if err != nil {
+		t.Fatalf("create temp dir: %v", err)
+	}
+
+	dbPath := filepath.Join(tmpDir, "test.db")
+	cfg := Config{
+		Path:     dbPath,
+		MaxConns: 4,
+		LogLevel: logger.Silent,
+	}
+
+	store, err := NewStore(cfg)
+	if err != nil {
+		os.RemoveAll(tmpDir)
+		t.Fatalf("NewStore failed: %v", err)
+	}
+
+	summaryStore := NewSummaryStore(store)
+
+	cleanup := func() {
+		store.Close()
+		os.RemoveAll(tmpDir)
+	}
+
+	return summaryStore, store, cleanup
+}
+
+func TestSummaryStore_StoreSummary(t *testing.T) {
+	summaryStore, store, cleanup := testSummaryStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create a session first
+	sessionStore := NewSessionStore(store)
+	_, err := sessionStore.CreateSDKSession(ctx, "claude-1", "test-project", "")
+	require.NoError(t, err)
+
+	// Store a summary
+	summary := &models.ParsedSummary{
+		Request:      "Build a feature",
+		Investigated: "Examined the codebase",
+		Learned:      "Discovered patterns",
+		Completed:    "Implemented solution",
+		NextSteps:    "Write tests",
+		Notes:        "Additional notes",
+	}
+
+	id, epoch, err := summaryStore.StoreSummary(ctx, "claude-1", "test-project", summary, 1, 100)
+	require.NoError(t, err)
+	assert.Greater(t, id, int64(0))
+	assert.Greater(t, epoch, int64(0))
+}
+
+func TestSummaryStore_StoreSummary_AutoCreateSession(t *testing.T) {
+	summaryStore, _, cleanup := testSummaryStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Store summary without pre-creating session
+	summary := &models.ParsedSummary{
+		Request: "Test auto-create",
+	}
+
+	id, _, err := summaryStore.StoreSummary(ctx, "claude-auto", "auto-project", summary, 1, 50)
+	require.NoError(t, err)
+	assert.Greater(t, id, int64(0))
+}
+
+func TestSummaryStore_GetRecentSummaries(t *testing.T) {
+	summaryStore, _, cleanup := testSummaryStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Store multiple summaries
+	for i := 1; i <= 5; i++ {
+		summary := &models.ParsedSummary{
+			Request: "Request " + string(rune('0'+i)),
+		}
+		_, _, err := summaryStore.StoreSummary(ctx, "claude-1", "project-a", summary, i, 10)
+		require.NoError(t, err)
+	}
+
+	// Store summary for different project
+	summary := &models.ParsedSummary{Request: "Other project"}
+	_, _, err := summaryStore.StoreSummary(ctx, "claude-2", "project-b", summary, 1, 10)
+	require.NoError(t, err)
+
+	// Get recent summaries for project-a
+	summaries, err := summaryStore.GetRecentSummaries(ctx, "project-a", 10)
+	require.NoError(t, err)
+	assert.Len(t, summaries, 5)
+
+	// Verify ordering (most recent first)
+	assert.Equal(t, "project-a", summaries[0].Project)
+}
+
+func TestSummaryStore_GetAllRecentSummaries(t *testing.T) {
+	summaryStore, _, cleanup := testSummaryStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Store summaries across projects
+	_, _, err := summaryStore.StoreSummary(ctx, "claude-1", "project-a", &models.ParsedSummary{Request: "A1"}, 1, 10)
+	require.NoError(t, err)
+
+	_, _, err = summaryStore.StoreSummary(ctx, "claude-2", "project-b", &models.ParsedSummary{Request: "B1"}, 1, 10)
+	require.NoError(t, err)
+
+	_, _, err = summaryStore.StoreSummary(ctx, "claude-3", "project-c", &models.ParsedSummary{Request: "C1"}, 1, 10)
+	require.NoError(t, err)
+
+	// Get all recent summaries
+	summaries, err := summaryStore.GetAllRecentSummaries(ctx, 10)
+	require.NoError(t, err)
+	assert.Len(t, summaries, 3)
+}
+
+func TestSummaryStore_GetSummariesByIDs(t *testing.T) {
+	summaryStore, _, cleanup := testSummaryStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Store multiple summaries
+	var ids []int64
+	for i := 1; i <= 3; i++ {
+		id, _, err := summaryStore.StoreSummary(ctx, "claude-1", "project-a", &models.ParsedSummary{Request: "Test"}, i, 10)
+		require.NoError(t, err)
+		ids = append(ids, id)
+	}
+
+	// Get by IDs
+	summaries, err := summaryStore.GetSummariesByIDs(ctx, ids, "date_desc", 10)
+	require.NoError(t, err)
+	assert.Len(t, summaries, 3)
+
+	// Get with limit
+	summaries, err = summaryStore.GetSummariesByIDs(ctx, ids, "date_desc", 2)
+	require.NoError(t, err)
+	assert.Len(t, summaries, 2)
+}
+
+func TestSummaryStore_GetSummariesByIDs_EmptyInput(t *testing.T) {
+	summaryStore, _, cleanup := testSummaryStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Get with empty IDs
+	summaries, err := summaryStore.GetSummariesByIDs(ctx, []int64{}, "date_desc", 10)
+	require.NoError(t, err)
+	assert.Nil(t, summaries)
+}
+
+func TestSummaryStore_SummaryFields(t *testing.T) {
+	summaryStore, _, cleanup := testSummaryStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Store a summary with all fields
+	summary := &models.ParsedSummary{
+		Request:      "Full request",
+		Investigated: "Full investigation",
+		Learned:      "Full learning",
+		Completed:    "Full completion",
+		NextSteps:    "Full next steps",
+		Notes:        "Full notes",
+	}
+
+	id, epoch, err := summaryStore.StoreSummary(ctx, "claude-1", "test-project", summary, 5, 200)
+	require.NoError(t, err)
+
+	// Retrieve and verify all fields
+	summaries, err := summaryStore.GetSummariesByIDs(ctx, []int64{id}, "date_desc", 1)
+	require.NoError(t, err)
+	require.Len(t, summaries, 1)
+
+	s := summaries[0]
+	assert.Equal(t, id, s.ID)
+	assert.Equal(t, "claude-1", s.SDKSessionID)
+	assert.Equal(t, "test-project", s.Project)
+	assert.True(t, s.Request.Valid)
+	assert.Equal(t, "Full request", s.Request.String)
+	assert.True(t, s.Investigated.Valid)
+	assert.Equal(t, "Full investigation", s.Investigated.String)
+	assert.True(t, s.Learned.Valid)
+	assert.Equal(t, "Full learning", s.Learned.String)
+	assert.True(t, s.Completed.Valid)
+	assert.Equal(t, "Full completion", s.Completed.String)
+	assert.True(t, s.NextSteps.Valid)
+	assert.Equal(t, "Full next steps", s.NextSteps.String)
+	assert.True(t, s.Notes.Valid)
+	assert.Equal(t, "Full notes", s.Notes.String)
+	assert.True(t, s.PromptNumber.Valid)
+	assert.Equal(t, int64(5), s.PromptNumber.Int64)
+	assert.Equal(t, int64(200), s.DiscoveryTokens)
+	assert.NotEmpty(t, s.CreatedAt)
+	assert.Equal(t, epoch, s.CreatedAtEpoch)
+}
+
+func TestSummaryStore_EmptySummary(t *testing.T) {
+	summaryStore, _, cleanup := testSummaryStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Store a summary with empty fields
+	summary := &models.ParsedSummary{}
+
+	id, _, err := summaryStore.StoreSummary(ctx, "claude-1", "test-project", summary, 0, 0)
+	require.NoError(t, err)
+
+	// Retrieve and verify NULL fields
+	summaries, err := summaryStore.GetSummariesByIDs(ctx, []int64{id}, "date_desc", 1)
+	require.NoError(t, err)
+	require.Len(t, summaries, 1)
+
+	s := summaries[0]
+	assert.False(t, s.Request.Valid)
+	assert.False(t, s.Investigated.Valid)
+	assert.False(t, s.Learned.Valid)
+	assert.False(t, s.Completed.Valid)
+	assert.False(t, s.NextSteps.Valid)
+	assert.False(t, s.Notes.Valid)
+	assert.False(t, s.PromptNumber.Valid)
+	assert.Equal(t, int64(0), s.DiscoveryTokens)
+}
+
+func TestSummaryStore_GetAllSummaries(t *testing.T) {
+	summaryStore, _, cleanup := testSummaryStore(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Store multiple summaries
+	for i := 1; i <= 5; i++ {
+		_, _, err := summaryStore.StoreSummary(ctx, "claude-1", "project-a", &models.ParsedSummary{Request: "Test"}, i, 10)
+		require.NoError(t, err)
+	}
+
+	// Get all summaries
+	summaries, err := summaryStore.GetAllSummaries(ctx)
+	require.NoError(t, err)
+	assert.Len(t, summaries, 5)
+
+	// Verify ordering by ID
+	for i := 0; i < len(summaries)-1; i++ {
+		assert.Less(t, summaries[i].ID, summaries[i+1].ID)
+	}
+}