memory

package
v0.0.102 Latest Latest
Warning

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

 Go to latest Published: Mar 2, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	DefaultSourceMine = "mine"
)

Variables

This section is empty.

Functions

func GetDBPath 

func GetDBPath() (string, error)

GetDBPath returns the default memory.db path.

func GetDataDir 

func GetDataDir() (string, error)

GetDataDir returns the XDG data directory for term-llm.

func ResolveDBPath 

func ResolveDBPath(pathOverride string) (string, error)

ResolveDBPath resolves an optional DB path override.

Types

type Config 

type Config struct {
	Path string // Optional DB path override (supports :memory:)
}

Config controls memory store initialization.

type Fragment 

type Fragment struct {
	ID          string
	RowID       int64
	Agent       string
	Path        string
	Content     string
	Source      string
	CreatedAt   time.Time
	UpdatedAt   time.Time
	AccessedAt  *time.Time
	AccessCount int
	DecayScore  float64
	Pinned      bool
}

Fragment is a durable memory item extracted from sessions.

type FragmentSource added in v0.0.101 

type FragmentSource struct {
	ID        int64
	Agent     string
	Path      string
	SessionID string
	TurnStart int
	TurnEnd   int
	CreatedAt time.Time
}

FragmentSource records a link between a memory fragment (L1) and the raw session turn range (L2) that the fragment was mined from. One fragment can accumulate many sources over time as the miner revisits sessions.

type ImageListOptions added in v0.0.94 

type ImageListOptions struct {
	Agent  string
	Limit  int
	Offset int
}

ImageListOptions controls listing of generated images.

type ImageRecord added in v0.0.94 

type ImageRecord struct {
	ID         string    `json:"id"`
	Agent      string    `json:"agent"`
	SessionID  string    `json:"session_id"`
	Prompt     string    `json:"prompt"`
	OutputPath string    `json:"output_path"`
	MimeType   string    `json:"mime_type"`
	Provider   string    `json:"provider"`
	Width      int       `json:"width"`
	Height     int       `json:"height"`
	FileSize   int       `json:"file_size"`
	CreatedAt  time.Time `json:"created_at"`
}

ImageRecord is a record of a generated image.

type ListOptions 

type ListOptions struct {
	Agent      string
	Since      *time.Time
	Limit      int
	PathFilter string // substring match on path (case-insensitive)
}

ListOptions configures fragment listing.

type MiningState 

type MiningState struct {
	SessionID       string
	Agent           string
	LastMinedOffset int
	MinedAt         time.Time
}

MiningState tracks per-session mining progress.

type ScoredFragment added in v0.0.94 

type ScoredFragment struct {
	ID          string    `json:"id"`
	Agent       string    `json:"agent"`
	Path        string    `json:"path"`
	Content     string    `json:"-"`
	Source      string    `json:"-"`
	CreatedAt   time.Time `json:"-"`
	UpdatedAt   time.Time `json:"-"`
	AccessedAt  *time.Time
	AccessCount int       `json:"-"`
	DecayScore  float64   `json:"-"`
	Pinned      bool      `json:"-"`
	Snippet     string    `json:"snippet"`
	Score       float64   `json:"score"`
	Vector      []float64 `json:"-"`
}

ScoredFragment is a fragment paired with a relevance score.

type SearchResult 

type SearchResult struct {
	Agent   string  `json:"agent"`
	Path    string  `json:"path"`
	Snippet string  `json:"snippet"`
	Score   float64 `json:"score"`
}

SearchResult is a BM25 result from FTS.

type Store 

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

Store persists memory fragments and mining state.

func NewStore 

func NewStore(cfg Config) (*Store, error)

NewStore opens memory.db and initializes schema.

func (*Store) AddFragmentSource added in v0.0.101 

func (s *Store) AddFragmentSource(ctx context.Context, agent, path, sessionID string, turnStart, turnEnd int) error

AddFragmentSource records that the fragment at (agent, path) was derived from messages [turnStart, turnEnd) of sessionID. Duplicate rows (same agent, path, session, and turn range) are silently ignored.

func (*Store) BumpAccess added in v0.0.94 

func (s *Store) BumpAccess(ctx context.Context, fragmentID string) error

BumpAccess marks a fragment as recently accessed, increments access_count, and gives decay_score a small recency boost.

func (*Store) Close 

func (s *Store) Close() error

Close closes the underlying DB.

func (*Store) CountGCCandidates added in v0.0.94 

func (s *Store) CountGCCandidates(ctx context.Context, agent string) (int, error)

CountGCCandidates counts fragments eligible for GC.

func (*Store) CreateFragment 

func (s *Store) CreateFragment(ctx context.Context, f *Fragment) error

CreateFragment inserts a new fragment and syncs FTS explicitly.

func (*Store) DeleteFragment 

func (s *Store) DeleteFragment(ctx context.Context, agent, path string) (deleted bool, err error)

DeleteFragment removes a fragment and syncs FTS. Returns deleted=false when no matching fragment exists.

func (*Store) DeleteFragmentByRowID added in v0.0.97 

func (s *Store) DeleteFragmentByRowID(ctx context.Context, rowID int64) (deleted bool, err error)

DeleteFragmentByRowID removes a fragment by its SQLite rowid. Returns deleted=false if no fragment with that rowid exists.

func (*Store) FindFragmentsByPath 

func (s *Store) FindFragmentsByPath(ctx context.Context, path string) ([]Fragment, error)

FindFragmentsByPath fetches fragments for a path across all agents.

func (*Store) FragmentCountsByAgent 

func (s *Store) FragmentCountsByAgent(ctx context.Context) (map[string]int, error)

FragmentCountsByAgent returns count(fragment) grouped by agent.

func (*Store) GCFragments added in v0.0.94 

func (s *Store) GCFragments(ctx context.Context, agent string) (int, error)

GCFragments deletes decayed, non-pinned fragments and keeps FTS in sync.

func (*Store) GetEmbedding added in v0.0.94 

func (s *Store) GetEmbedding(ctx context.Context, fragmentID, provider, model string) ([]float64, error)

GetEmbedding fetches a stored embedding vector for a fragment+provider+model.

func (*Store) GetEmbeddingsByIDs added in v0.0.94 

func (s *Store) GetEmbeddingsByIDs(ctx context.Context, fragmentIDs []string, provider, model string) (map[string][]float64, error)

func (*Store) GetFragment 

func (s *Store) GetFragment(ctx context.Context, agent, path string) (*Fragment, error)

GetFragment fetches a fragment by (agent,path).

func (*Store) GetFragmentByRowID added in v0.0.96 

func (s *Store) GetFragmentByRowID(ctx context.Context, rowID int64) (*Fragment, error)

GetFragmentByRowID fetches a fragment by its SQLite rowid.

func (*Store) GetFragmentSources added in v0.0.101 

func (s *Store) GetFragmentSources(ctx context.Context, agent, path string) ([]FragmentSource, error)

GetFragmentSources returns all source records for a given (agent, path) fragment, ordered oldest first.

func (*Store) GetFragmentsNeedingEmbedding added in v0.0.94 

func (s *Store) GetFragmentsNeedingEmbedding(ctx context.Context, agent, provider, model string) ([]Fragment, error)

GetFragmentsNeedingEmbedding returns fragments missing an embedding row for provider+model.

func (*Store) GetMeta added in v0.0.94 

func (s *Store) GetMeta(ctx context.Context, key string) (string, error)

GetMeta returns a value from memory_meta. Missing keys return "", nil.

func (*Store) GetSourcesForSession added in v0.0.101 

func (s *Store) GetSourcesForSession(ctx context.Context, sessionID string) ([]FragmentSource, error)

GetSourcesForSession returns all fragment sources that were derived from a given session, ordered by path. Useful for auditing what a session produced.

func (*Store) GetState 

func (s *Store) GetState(ctx context.Context, sessionID string) (*MiningState, error)

GetState returns mining state for a session.

func (*Store) LastMinedByAgent 

func (s *Store) LastMinedByAgent(ctx context.Context) (map[string]time.Time, error)

LastMinedByAgent returns MAX(mined_at) grouped by agent.

SQLite aggregate functions like MAX() return the underlying value as a plain string, bypassing the driver's column-type inference that makes direct column scans into time.Time work. We therefore scan as a string and parse manually, accepting both RFC3339 (current format written by UpsertState) and the legacy Go time.String() format that older rows may contain.

func (*Store) ListAgents added in v0.0.94 

func (s *Store) ListAgents(ctx context.Context) ([]string, error)

ListAgents returns distinct agent names that have stored fragments.

func (*Store) ListFragments 

func (s *Store) ListFragments(ctx context.Context, opts ListOptions) ([]Fragment, error)

ListFragments returns fragments sorted by created_at descending (most recently learned first). updated_at is only bumped when content actually changes, so ordering by it would give misleading results when many fragments happen to be updated in the same batch. RowID is populated on each returned Fragment.

func (*Store) ListImageAgents added in v0.0.94 

func (s *Store) ListImageAgents(ctx context.Context) ([]string, error)

ListImageAgents returns distinct agent names for generated images.

func (*Store) ListImages added in v0.0.94 

func (s *Store) ListImages(ctx context.Context, opts ImageListOptions) ([]ImageRecord, error)

ListImages returns generated images ordered by creation time (newest first).

func (*Store) ListImagesSince added in v0.0.94 

func (s *Store) ListImagesSince(ctx context.Context, agent string, since time.Time) ([]ImageRecord, error)

ListImagesSince returns generated images for an agent created after the given time.

func (*Store) RecalcDecayScores added in v0.0.94 

func (s *Store) RecalcDecayScores(ctx context.Context, agent string, halfLifeDays float64) (int, error)

RecalcDecayScores recalculates decay_score for non-pinned fragments. halfLifeDays defaults to 30 when <= 0.

func (*Store) RecordImage added in v0.0.94 

func (s *Store) RecordImage(ctx context.Context, r *ImageRecord) error

RecordImage inserts a generated image record into the store. Non-fatal in callers: errors do not stop image generation.

func (*Store) SearchBM25 added in v0.0.94 

func (s *Store) SearchBM25(ctx context.Context, query string, limit int, agent string) ([]ScoredFragment, error)

SearchBM25 performs BM25 search over FTS5 and returns fragment details.

func (*Store) SearchFragments 

func (s *Store) SearchFragments(ctx context.Context, query string, limit int, agent string) ([]SearchResult, error)

SearchFragments performs BM25 search over FTS5.

func (*Store) SearchImages added in v0.0.94 

func (s *Store) SearchImages(ctx context.Context, query, agent string, limit int) ([]ImageRecord, error)

SearchImages searches generated images by prompt/path using FTS5.

func (*Store) SetMeta added in v0.0.94 

func (s *Store) SetMeta(ctx context.Context, key, value string) error

SetMeta upserts a key/value pair in memory_meta.

func (*Store) UpdateFragment 

func (s *Store) UpdateFragment(ctx context.Context, agent, path, content string) (updated bool, err error)

UpdateFragment updates content for an existing (agent,path) fragment and syncs FTS. Returns updated=false when no matching fragment exists or content is identical (no-op). updated_at is only bumped when content actually changes.

func (*Store) UpdateFragmentByRowID added in v0.0.97 

func (s *Store) UpdateFragmentByRowID(ctx context.Context, rowID int64, content string) (updated bool, err error)

UpdateFragmentByRowID updates a fragment looked up by its SQLite rowid. Returns updated=false if no fragment with that rowid exists, or content is unchanged.

func (*Store) UpsertEmbedding added in v0.0.94 

func (s *Store) UpsertEmbedding(ctx context.Context, fragmentID, provider, model string, dims int, vec []float64) error

UpsertEmbedding inserts or updates an embedding vector for a fragment.

func (*Store) UpsertState 

func (s *Store) UpsertState(ctx context.Context, st *MiningState) error

UpsertState inserts or updates mining state.

func (*Store) VectorSearch added in v0.0.94 

func (s *Store) VectorSearch(ctx context.Context, agent, provider, model string, queryVec []float64, limit int) ([]ScoredFragment, error)

VectorSearch performs a full cosine similarity scan over embeddings.

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.