AI Memory System

A Go library that stores and ranks memories, ages them on each read, retrieves top results plus a few random ones, and reranks based on feedback.

Specifics:

• Number of top memories and random retrievals are configurable based on use case
• Reranking changes the score of each memory. This is determined by: freshness (age), how often it was useful, and whether it was randomly recalled

Usage

store := storage.NewInMemoryStorage()
ranker := ranking.NewStandardRanking(nil)
ms := memory.NewService(store, ranker)

// Add memories
ms.AddMemory(ctx, "Liam likes Go")

// Get top memories
memories, _ := ms.ListBestMemories(ctx, 10, 1)

// Provide feedback to re-rank
ms.FeedbackMemories(ctx, feedback)

Running the simulation

# Run full simulation with detailed output
go run .

# Run only the final analysis (useful for
# large number of rounds)
go run . -finalOnly

Adjust constants in sim/sim.go for realistic scenarios:

rounds         int = 100  // Memory addition cycles
readOnlyRounds int = 400  // Read-only cycles between additions

---

1 - Domain Model

type Memory struct {
	ID            string
	Content       string
	Rating        float64
	CreatedAt     time.Time
	FeedbackCount int
	Age           int
}

Lifecycle

1. Add → rating = INITIAL_RATING, feedbackCount = 0, age = 0, createdAt = now
2. Read → increment age for all memories (each list call = one cycle) and order by Rating
3. Feedback → CalibrateRating(memory, useful) per read item
4. Auto-remove (optional) → delete when heavily aged and low-quality

---

2 - Architecture

• model/model.go defines models and interfaces, for example model.Ranking and model.Storage.
• ranking/ contains implementations of model.Ranking.
• storage/ contains implementations of model.Storage.
• memory/memory.go contains the main service that uses the ranking and storage implementations.

Note: Today there is a single implementation of each interface:

• ranking/standardranking.go implements model.Ranking via StandardRanking.
• storage/inmemorystorage.go implements model.Storage via InMemoryStorage.

Additional implementations (e.g., storage/dbstorage.go) can be added later without changing the rest of the system.

---

3 - Rating Calibration

3.1 - CalibrateRating

Combines freshness-augmented expectation, staleness-aware K, and exploration into a single update:

// effectiveRating = Rating + freshness(Age)
// expected = logistic(baselineRating - effectiveRating)
// kBase = kfactor(FeedbackCount, Age)
// explorationFactor = 1 + explorationBonus(FeedbackCount, Age)/400
// k = kBase * explorationFactor
// Rating += k * (actual - expected)
// FeedbackCount++

Defaults:

initialRating   = 1200
baselineRating  = 1500
kFactorInitial  = 64
kFactorMin      = 8
lambdaStaleness = 0.5
recencyBoost    = 400
halfLifeAge     = 4
explorationBonus scale used inside calibration

3.2 - Removal Rule (optional)

return memory.Rating < rs.config.ratingFloor && rs.freshness(memory.Age) < 1

---

4 - Implementation Reference

• model/Memory{}: no Score field
• storage/inmemorystorage.go TopIDsByScore: sorts by Rating descending
• memory.ListBestMemories: increments age only, does not mutate ratings
• memory.FeedbackMemories: applies CalibrateRating (exploration built-in)
• ranking.StandardRanking.CalibrateRating: unified function