memory

package
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 13, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package memory provides a hierarchical long-term memory system for gleann.

Memory is organized into three tiers:

  • Short-term (in-memory): Active conversation notes, ephemeral context
  • Medium-term (BBolt): Daily summaries, conversation digests
  • Long-term (BBolt): Persistent facts, user preferences, archived knowledge

Inspired by Letta's memory block architecture, adapted for gleann's RAG pipeline.

Package memory — Sleep-time compute engine.

Inspired by Letta's sleep-time agents, this subsystem runs a background goroutine that periodically reflects on recent conversations and autonomously updates memory blocks. It extracts key facts, prunes contradictions, and promotes important information — without blocking the interactive flow.

Configuration (env vars): 

GLEANN_SLEEPTIME_ENABLED      — "1" or "true" to enable (default: disabled)
GLEANN_SLEEPTIME_INTERVAL     — how often to run, Go duration (default: 30m)
GLEANN_SLEEPTIME_MAX_CONVS    — max recent conversations per cycle (default: 5)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultStorePath 

func DefaultStorePath() string

DefaultStorePath returns the default memory database path.

Types

type Block 

type Block struct {
	ID        string            `json:"id"`       // Unique identifier (UUID-like or content hash)
	Tier      Tier              `json:"tier"`     // Storage tier
	Label     string            `json:"label"`    // Semantic label (e.g. "user_preference", "conversation_summary")
	Content   string            `json:"content"`  // The memory content
	Source    string            `json:"source"`   // Origin: "user", "auto_summary", "system", "sleep_time"
	Tags      []string          `json:"tags"`     // Searchable tags
	Metadata  map[string]string `json:"metadata"` // Arbitrary key-value metadata
	CreatedAt time.Time         `json:"created_at"`
	UpdatedAt time.Time         `json:"updated_at"`
	ExpiresAt *time.Time        `json:"expires_at"` // nil = never expires

	// Character limit for this block's content. 0 = unlimited.
	// When content exceeds this limit, it is truncated or compressed.
	CharLimit int `json:"char_limit,omitempty"`

	// Scope isolates the block to a specific context (e.g. conversation ID,
	// session ID, or a named group). Empty string means global (visible everywhere).
	Scope string `json:"scope,omitempty"`
}

Block represents a single memory entry.

func (*Block) ExceedsLimit 

func (b *Block) ExceedsLimit() bool

ExceedsLimit returns true if the block's content exceeds its character limit. Returns false when CharLimit is 0 (unlimited).

func (*Block) IsExpired 

func (b *Block) IsExpired() bool

IsExpired returns true if the block has passed its expiration date.

func (*Block) TruncateToLimit 

func (b *Block) TruncateToLimit()

TruncateToLimit trims content to the character limit if exceeded. Appends "... [truncated]" when trimming occurs.

type ContextWindow 

type ContextWindow struct {
	ShortTerm  []Block   `json:"short_term,omitempty"`
	MediumTerm []Block   `json:"medium_term,omitempty"`
	LongTerm   []Block   `json:"long_term,omitempty"`
	Summaries  []Summary `json:"summaries,omitempty"`
}

ContextWindow represents compiled memory for LLM injection.

func (*ContextWindow) Render 

func (cw *ContextWindow) Render() string

Render compiles the context window into a formatted string for LLM consumption.

type Manager 

type Manager struct {

	// Configuration.
	ShortTermTTL     time.Duration // Default TTL for short-term blocks (0 = session only)
	MediumTermMaxAge time.Duration // Auto-archive medium-term blocks older than this
	AutoPromote      bool          // Auto-promote short-term blocks on session end
	AutoCleanup      bool          // Auto-cleanup expired blocks

	// Character limit defaults (Letta-inspired).
	DefaultCharLimit int  // Default char limit for new blocks (0 = unlimited)
	EnforceCharLimit bool // Whether to truncate blocks that exceed their limit on Add
	// contains filtered or unexported fields
}

Manager provides a high-level interface to the memory system with automatic lifecycle management (promotion, cleanup, expiration).

func DefaultManager 

func DefaultManager() (*Manager, error)

DefaultManager opens the default store and returns a manager.

func NewManager 

func NewManager(store *Store) *Manager

NewManager creates a new memory manager wrapping the given store.

func (*Manager) AddNote 

func (m *Manager) AddNote(tier Tier, label, content string, tags ...string) (*Block, error)

AddNote adds a note to the specified tier.

func (*Manager) AddScopedNote 

func (m *Manager) AddScopedNote(scope string, tier Tier, label, content string, tags ...string) (*Block, error)

AddScopedNote adds a note scoped to a specific context (e.g. conversation).

func (*Manager) BuildContext 

func (m *Manager) BuildContext() (*ContextWindow, error)

BuildContext compiles memory into a ContextWindow for LLM injection.

func (*Manager) BuildScopedContext 

func (m *Manager) BuildScopedContext(scope string) (*ContextWindow, error)

BuildScopedContext compiles memory visible to a specific scope. Includes both global blocks (scope="") and blocks matching the given scope.

func (*Manager) Clear 

func (m *Manager) Clear(tier Tier) (int, error)

Clear removes all blocks from the specified tier. This is the /clear command equivalent.

func (*Manager) ClearAll 

func (m *Manager) ClearAll() (int, error)

ClearAll removes all blocks from all tiers.

func (*Manager) Close 

func (m *Manager) Close() error

Close closes the underlying store.

func (*Manager) EndSession 

func (m *Manager) EndSession() error

EndSession handles session end: promotes short-term notes and cleans up.

func (*Manager) Forget 

func (m *Manager) Forget(idOrQuery string) (int, error)

Forget removes a memory block by ID or content match. This is the /forget command equivalent.

func (*Manager) List 

func (m *Manager) List(tier Tier) ([]Block, error)

List lists all blocks for a tier (empty string = all tiers).

func (*Manager) ListScoped 

func (m *Manager) ListScoped(scope string, tier Tier) ([]Block, error)

ListScoped lists blocks for a tier within a specific scope plus global blocks.

func (*Manager) Remember 

func (m *Manager) Remember(content string, tags ...string) (*Block, error)

Remember adds important information to long-term memory. This is the /remember command equivalent.

func (*Manager) RunMaintenance 

func (m *Manager) RunMaintenance() error

RunMaintenance performs periodic maintenance: - Prune expired blocks - Archive old medium-term blocks to long-term - Clean up old summaries

func (*Manager) Search 

func (m *Manager) Search(query string) ([]Block, error)

Search searches across all memory tiers.

func (*Manager) SearchScoped 

func (m *Manager) SearchScoped(scope, query string) ([]Block, error)

SearchScoped searches within a specific scope plus global blocks.

func (*Manager) Stats 

func (m *Manager) Stats() (*Stats, error)

Stats returns memory statistics.

func (*Manager) Store 

func (m *Manager) Store() *Store

Store returns the underlying Store for direct access.

type SleepTimeConfig 

type SleepTimeConfig struct {
	Enabled       bool
	Interval      time.Duration
	MaxConvs      int // Max recent conversations to process per cycle.
	ConvStore     *conversations.Store
	SummarizerCfg SummarizerConfig
}

SleepTimeConfig holds configuration for the sleep-time compute engine.

func DefaultSleepTimeConfig 

func DefaultSleepTimeConfig() SleepTimeConfig

DefaultSleepTimeConfig returns the default configuration, reading env vars.

type SleepTimeEngine 

type SleepTimeEngine struct {
	// contains filtered or unexported fields
}

SleepTimeEngine runs background reflection on conversations.

func NewSleepTimeEngine 

func NewSleepTimeEngine(mgr *Manager, cfg SleepTimeConfig) *SleepTimeEngine

NewSleepTimeEngine creates a new sleep-time engine.

func (*SleepTimeEngine) RunOnce 

func (e *SleepTimeEngine) RunOnce(ctx context.Context) error

RunOnce executes a single sleep-time cycle synchronously. Useful for testing.

func (*SleepTimeEngine) Start 

func (e *SleepTimeEngine) Start(stopCh <-chan struct{})

Start launches the background goroutine. It stops when stopCh is closed.

type Stats 

type Stats struct {
	ShortTermCount  int   `json:"short_term_count"`
	MediumTermCount int   `json:"medium_term_count"`
	LongTermCount   int   `json:"long_term_count"`
	TotalCount      int   `json:"total_count"`
	DiskSizeBytes   int64 `json:"disk_size_bytes"`
}

Stats holds memory system statistics.

type Store 

type Store struct {
	// contains filtered or unexported fields
}

Store provides persistent memory storage backed by BBolt. Short-term blocks are kept in-memory with optional BBolt persistence. Medium-term and long-term blocks are always persisted.

func DefaultStore 

func DefaultStore() (*Store, error)

DefaultStore opens the default memory store.

func OpenStore 

func OpenStore(path string) (*Store, error)

OpenStore opens or creates a memory store at the given path.

func (*Store) Add 

func (s *Store) Add(block *Block) error

Add stores a new memory block. Short-term blocks are kept in-memory; medium and long-term blocks are persisted to BBolt.

func (*Store) BuildContext 

func (s *Store) BuildContext() (*ContextWindow, error)

BuildContext compiles all active memory into a ContextWindow for LLM injection.

func (*Store) ClearAll 

func (s *Store) ClearAll() (int, error)

ClearAll removes all blocks from all tiers.

func (*Store) ClearTier 

func (s *Store) ClearTier(tier Tier) (int, error)

ClearTier removes all blocks for a given tier.

func (*Store) Close 

func (s *Store) Close() error

Close closes the underlying database.

func (*Store) Delete 

func (s *Store) Delete(id string) error

Delete removes a block by ID.

func (*Store) DeleteOlderThan 

func (s *Store) DeleteOlderThan(tier Tier, d time.Duration) (int, error)

DeleteOlderThan removes blocks older than the given duration from the specified tier.

func (*Store) DeleteSummariesOlderThan 

func (s *Store) DeleteSummariesOlderThan(d time.Duration) (int, error)

DeleteSummariesOlderThan removes summaries older than the given duration.

func (*Store) Get 

func (s *Store) Get(id string) (*Block, error)

Get retrieves a block by ID. Checks short-term first, then BBolt.

func (*Store) List 

func (s *Store) List(tier Tier) ([]Block, error)

List returns all blocks for a given tier, sorted by creation time (newest first). If tier is empty, returns all blocks across all tiers.

func (*Store) ListSummaries 

func (s *Store) ListSummaries() ([]Summary, error)

ListSummaries returns all summaries, newest first.

func (*Store) Path 

func (s *Store) Path() string

Path returns the database file path.

func (*Store) Promote 

func (s *Store) Promote(id string, target Tier) error

Promote moves a block from one tier to a higher (longer-lived) tier.

func (*Store) PruneExpired 

func (s *Store) PruneExpired() (int, error)

PruneExpired removes all expired blocks from all tiers.

func (*Store) SaveSummary 

func (s *Store) SaveSummary(summary *Summary) error

SaveSummary stores a conversation summary.

func (*Store) Search 

func (s *Store) Search(query string) ([]Block, error)

Search returns blocks whose content or label contains the query (case-insensitive).

func (*Store) Stats 

func (s *Store) Stats() (*Stats, error)

Stats returns memory statistics.

type Summarizer 

type Summarizer struct {
	// contains filtered or unexported fields
}

Summarizer generates conversation summaries for memory storage.

func NewSummarizer 

func NewSummarizer(cfg SummarizerConfig) *Summarizer

NewSummarizer creates a new summarizer with the given configuration.

func (*Summarizer) ExtractMemories 

func (s *Summarizer) ExtractMemories(ctx context.Context, conv *conversations.Conversation) ([]Block, error)

ExtractMemories analyzes a conversation and extracts important facts that should be stored as long-term memories.

func (*Summarizer) SummarizeConversation 

func (s *Summarizer) SummarizeConversation(ctx context.Context, conv *conversations.Conversation) (*Summary, error)

SummarizeConversation generates a concise summary of a conversation. The summary captures key topics, decisions, and important facts.

type SummarizerConfig 

type SummarizerConfig struct {
	Provider string // "ollama", "openai", "anthropic"
	Model    string
	BaseURL  string
	APIKey   string
}

SummarizerConfig holds configuration for the auto-summarization LLM calls.

type Summary 

type Summary struct {
	ConversationID string    `json:"conversation_id"`
	Title          string    `json:"title"`
	Content        string    `json:"content"` // The summary text
	MessageCount   int       `json:"message_count"`
	IndexNames     []string  `json:"index_names"` // Which indexes were used
	Model          string    `json:"model"`       // LLM model used
	CreatedAt      time.Time `json:"created_at"`
}

Summary represents a conversation summary stored in medium-term memory.

type Tier 

type Tier string

Tier represents a memory storage tier. 

const (
	TierShort  Tier = "short"  // In-memory, session-scoped
	TierMedium Tier = "medium" // BBolt, daily summaries
	TierLong   Tier = "long"   // BBolt, permanent archive
)

func ParseTier 

func ParseTier(s string) (Tier, error)

ParseTier parses a tier string, returning an error for unknown tiers.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.