memory

package
v1.11.0 Latest Latest
Warning

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

 Go to latest Published: Sep 7, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	KindUser      = "user"
	KindFeedback  = "feedback"
	KindProject   = "project"
	KindReference = "reference"

	ScopeGlobal = "global"
)

Concept kinds and the global scope.

View Source 
const (
	// DefaultRecallK is how many concepts a per-turn recall returns.
	DefaultRecallK = 15
	// DefaultTopK is how many top-weighted concepts open a session.
	DefaultTopK = 15
	// DefaultBodies is how many of the leading concepts carry their body
	// inline; the rest are titles the model can expand with load_memory.
	DefaultBodies = 3
	// DefaultTopicK bounds the topic list shown to the model.
	DefaultTopicK = 20
	// DefaultHookTimeout caps how long recall operations can take.
	DefaultHookTimeout = 8 * time.Second
)
View Source 
const (
	WeightInitial = 1.0
	WeightCap     = 5.0
	WeightFloor   = 0.05

	// ImplicitBump is applied to every concept a recall returns.
	ImplicitBump = 0.05
	// ExplicitBump is the reinforce/demote magnitude; positive bumps are
	// log-dampened toward WeightCap so repeated calls cannot pin a concept.
	ExplicitBump = 0.5
	// RefractoryPeriod drops a second explicit bump on the same concept
	// inside the window, so an implicit recall bump followed by an
	// immediate reinforce is not double-counted.
	RefractoryPeriod = 60 * time.Second

	ConceptHalfLife = 100 * 24 * time.Hour
	TopicHalfLife   = 60 * 24 * time.Hour

	// Reranking: score = sim^RerankSimExp * weight^RerankWeightExp, then
	// TopicBoost for candidates in the turn's topic.
	RerankSimExp    = 1.0
	RerankWeightExp = 0.5
	TopicBoost      = 1.15

	// CandidateOversample is how many raw vector hits are pulled before
	// reranking; MaxDistance is the cosine-distance relevance floor.
	CandidateOversample = 50
	MaxDistance         = 0.4
)

Weight tunables. Weight is the running importance of a concept: it decays exponentially with disuse and is bumped whenever the concept is surfaced (implicit) or judged useful by the model (explicit).

Variables

View Source 
var Kinds = []string{KindUser, KindFeedback, KindProject, KindReference}

Kinds lists every valid concept kind.

Functions

func Close 

func Close() error

Close tears down the default process-wide memory service.

func ConceptLine 

func ConceptLine(c Concept) string

ConceptLine is the one-line index entry for a concept.

func DefaultDBPath 

func DefaultDBPath() (string, error)

DefaultDBPath returns the standard SQLite vector database file location.

func FileBlock 

func FileBlock(ctx context.Context, cwd, path string) string

FileBlock returns titles recalled for a touched file path, without a weight bump: a path match is weak evidence of relevance.

func FormatConcepts 

func FormatConcepts(concepts []Concept, heading, note string, bodies int) string

FormatConcepts renders concepts as a titled list: one line per concept as "#id [kind · topic] title", with the first bodies concepts carrying their body indented beneath.

func IsOpen 

func IsOpen() bool

IsOpen reports whether the default process-wide memory service is open.

func NormalizeTopic 

func NormalizeTopic(t string) string

NormalizeTopic lowercases, collapses whitespace, and caps a topic at three words so the taxonomy stays short.

func Open 

func Open(opts Options) error

Open initializes the default process-wide memory service.

func RecallBlock 

func RecallBlock(ctx context.Context, cwd, prompt, topic string, exclude map[int64]bool) (string, string)

RecallBlock returns the per-turn block for prompt and the topic the hits imply. ids already in the system block are dropped so a turn does not repeat what the session opened with.

func ScopeFor 

func ScopeFor(cwd string) string

ScopeFor maps a working directory to its memory scope: the project root, falling back to the cleaned cwd. An empty cwd has no scope.

func SerializeVector 

func SerializeVector(vec []float32) []byte

SerializeVector converts a float32 slice to the byte representation expected by sqlite-vec.

func SetDefault 

func SetDefault(s *Service)

SetDefault replaces the default global Service instance.

func SystemBlock 

func SystemBlock(ctx context.Context, cwd string) string

SystemBlock returns the session-start block: the top-weighted concepts for cwd's project and global scopes.

func TitleFromBody 

func TitleFromBody(body string) string

TitleFromBody derives a one-line title: the first non-empty line, clipped to 80 runes.

func TopIDs 

func TopIDs(ctx context.Context, cwd string) map[int64]bool

TopIDs returns the ids SystemBlock would show, so RecallBlock can skip them.

func Upsert 

func Upsert(ctx context.Context, c Concept) (int64, error)

Upsert stores a concept in the default service.

func ValidKind 

func ValidKind(k string) bool

ValidKind reports whether k is one of Kinds.

Types

type Concept 

type Concept struct {
	ID          int64     `json:"id"`
	Scope       string    `json:"scope"`
	Kind        string    `json:"kind"`
	Topic       string    `json:"topic,omitempty"`
	Title       string    `json:"title"`
	Body        string    `json:"body"`
	Weight      float64   `json:"weight"`
	AccessCount int64     `json:"access_count"`
	CreatedAt   time.Time `json:"created_at"`
	LastTouched time.Time `json:"last_touched"`

	// Distance and Score are set on recall hits only.
	Distance float32 `json:"distance,omitempty"`
	Score    float64 `json:"score,omitempty"`
}

Concept is one long-term memory: a one-line title that goes into prompts cheaply, a body fetched on demand, and a decaying weight.

type Embedder 

type Embedder interface {
	Embed(text string) ([]float32, error)
	EmbdSize() int
	Close()
}

Embedder represents a model capable of generating vector embeddings for text.

The store never loads a model itself: callers hand one in through Options.Embedder. cmd/ask uses the llama.cpp model in pkg/memory/llamacpp, the one place in the module that links llama.cpp; other consumers bring their own, and tests use NewFakeEmbedder.

type Extractor 

type Extractor interface {
	Enqueue(TurnRecord) bool
}

Extractor turns finished turns into concepts, asynchronously.

type FakeEmbedder 

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

FakeEmbedder is the deterministic test embedder: a hashed bag of words, L2-normalised, so texts sharing words land near each other and unrelated texts do not.

func NewFakeEmbedder 

func NewFakeEmbedder(dim int) *FakeEmbedder

func (*FakeEmbedder) Close 

func (f *FakeEmbedder) Close()

func (*FakeEmbedder) EmbdSize 

func (f *FakeEmbedder) EmbdSize() int

func (*FakeEmbedder) Embed 

func (f *FakeEmbedder) Embed(text string) ([]float32, error)

type Options 

type Options struct {
	DBPath string
	// Embedder produces the vectors the store indexes; required.
	Embedder Embedder
	// Now is the clock decay and refractory math read; nil means time.Now.
	Now func() time.Time
}

Options configures the initialization of the Memory Service.

type RecallQuery 

type RecallQuery struct {
	// Cwd selects the project scope; global concepts are always included.
	// Empty searches every scope.
	Cwd string
	// Query is embedded and matched against every concept.
	Query string
	// Topic is the caller's current topic, used when the hits do not agree
	// on one and to boost same-topic candidates.
	Topic string
	K     int
	// Silent skips the implicit weight bump on the returned concepts.
	Silent bool
}

RecallQuery describes one recall.

type RecallResult 

type RecallResult struct {
	Concepts []Concept
	// Topic is the dominant topic among the candidates, else Query.Topic.
	Topic string
}

RecallResult is the ranked hits plus the topic inferred from them.

func Recall 

func Recall(ctx context.Context, q RecallQuery) (RecallResult, error)

Recall queries the default service.

type Service 

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

Service manages concept persistence, retrieval, and weighting.

func Default 

func Default() *Service

Default returns the default global Service instance.

func NewService 

func NewService(opts Options) (*Service, error)

NewService initializes a SQLite-vec memory service with the specified options.

func (*Service) AddSessionToMemory 

func (s *Service) AddSessionToMemory(ctx context.Context, sess session.Session) error

AddSessionToMemory hands the session's last exchange to the installed Extractor. ADK calls this with a finished session; ask's own turn boundaries enqueue directly.

func (*Service) Close 

func (s *Service) Close() error

Close releases the database and embedding model.

func (*Service) Demote 

func (s *Service) Demote(ctx context.Context, id int64) (bool, error)

Demote applies a negative explicit bump, clamped at WeightFloor. The concept is never deleted.

func (*Service) Forget 

func (s *Service) Forget(ctx context.Context, id int64) error

Forget hard-deletes a concept and its vector.

func (*Service) Get 

func (s *Service) Get(ctx context.Context, id int64) (Concept, error)

Get returns one concept by id with its decayed weight.

func (*Service) IsOpen 

func (s *Service) IsOpen() bool

IsOpen reports whether the memory service is initialized and open.

func (*Service) Recall 

func (s *Service) Recall(ctx context.Context, q RecallQuery) (RecallResult, error)

Recall embeds the query, pulls the nearest candidates in the project and global scopes, reranks them by similarity and decayed weight, infers the turn's topic from them, and bumps what it returns.

func (*Service) Reinforce 

func (s *Service) Reinforce(ctx context.Context, id int64) (bool, error)

Reinforce applies a positive explicit bump. It reports false when the concept was explicitly touched inside RefractoryPeriod.

func (*Service) SearchMemory 

func (s *Service) SearchMemory(ctx context.Context, req *adkmemory.SearchRequest) (*adkmemory.SearchResponse, error)

SearchMemory is the ADK-shaped recall: every scope, no topic.

func (*Service) SetExtractor 

func (s *Service) SetExtractor(e Extractor)

SetExtractor installs the Extractor AddSessionToMemory hands turns to.

func (*Service) Top 

func (s *Service) Top(ctx context.Context, cwd string, k int) ([]Concept, error)

Top returns the highest-weighted concepts in the project and global scopes. No embedding, no bump: this is the session-start block.

func (*Service) TopicNames 

func (s *Service) TopicNames(ctx context.Context, cwd string, k int) []string

TopicNames is Topics reduced to names.

func (*Service) Topics 

func (s *Service) Topics(ctx context.Context, cwd string, k int) ([]Topic, error)

Topics returns the live topics for cwd's scope plus global, strongest first, deduplicated by name.

func (*Service) TouchTopic 

func (s *Service) TouchTopic(ctx context.Context, cwd, name string) error

TouchTopic creates or bumps a topic in cwd's scope (global when cwd is empty).

func (*Service) Upsert 

func (s *Service) Upsert(ctx context.Context, c Concept) (int64, error)

Upsert stores c: a zero ID inserts a new concept at WeightInitial; a positive ID rewrites that concept's text and re-embeds it, treating the rewrite as an implicit bump. Returns the concept id.

type Topic 

type Topic struct {
	ID          int64     `json:"id"`
	Scope       string    `json:"scope"`
	Name        string    `json:"name"`
	Weight      float64   `json:"weight"`
	LastTouched time.Time `json:"last_touched"`
}

Topic is a short label concepts are grouped under, weighted like a concept so stale topics fall out of the candidate list.

type TurnRecord 

type TurnRecord struct {
	Cwd      string
	Prompt   string
	Response string
	Topic    string
	Files    []string
}

TurnRecord is one finished conversational turn handed to an Extractor.

func TurnFromSession 

func TurnFromSession(sess session.Session) TurnRecord

TurnFromSession reduces a session to its last exchange: the final user text and every model text after it. Cwd comes from session state when a caller stored one.

Source Files

View all Source files

Directories

Path Synopsis
Package llamacpp is the llama.cpp embedder for the memory store: a GGUF embedding model driven through cgo against the static libraries under build/llama.cpp.
 Package llamacpp is the llama.cpp embedder for the memory store: a GGUF embedding model driven through cgo against the static libraries under build/llama.cpp.

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.