Documentation
¶
Overview ¶
Package memory provides observational memory for conversations.
It extracts observations from conversation turns (Observer) and synthesizes higher-level reflections from accumulated observations (Reflector). Memory is session-scoped and temporal — it captures what happened during a conversation, not persistent agent knowledge.
Buffer manages async processing with configurable token thresholds. GraphHooks generates temporal/session triples for the graph store.
Related packages:
- agentmemory: per-agent persistent memory (cross-session)
- knowledge: user-contributed knowledge store with multi-layer retrieval
- learning: pattern extraction from tool execution results
- graph: triple store for semantic relationships
Index ¶
- func BuildObservationTools(ms *Store) []*agent.Tool
- func CountMessageTokens(msg session.Message) int
- func CountMessagesTokens(msgs []session.Message) int
- func EstimateTokens(text string) int
- type Buffer
- type GraphHooks
- type MessageCompactor
- type MessageProvider
- type Observation
- type Observer
- type Reflection
- type Reflector
- type Store
- func (s *Store) DeleteObservations(ctx context.Context, ids []uuid.UUID) error
- func (s *Store) DeleteObservationsBySession(ctx context.Context, sessionKey string) error
- func (s *Store) DeleteReflections(ctx context.Context, ids []uuid.UUID) error
- func (s *Store) DeleteReflectionsBySession(ctx context.Context, sessionKey string) error
- func (s *Store) GetObservation(ctx context.Context, id uuid.UUID) (*Observation, error)
- func (s *Store) GetReflection(ctx context.Context, id uuid.UUID) (*Reflection, error)
- func (s *Store) ListObservations(ctx context.Context, sessionKey string) ([]Observation, error)
- func (s *Store) ListRecentObservations(ctx context.Context, sessionKey string, limit int) ([]Observation, error)
- func (s *Store) ListRecentReflections(ctx context.Context, sessionKey string, limit int) ([]Reflection, error)
- func (s *Store) ListReflections(ctx context.Context, sessionKey string) ([]Reflection, error)
- func (s *Store) SaveObservation(ctx context.Context, obs Observation) error
- func (s *Store) SaveReflection(ctx context.Context, ref Reflection) error
- func (s *Store) SetEventBus(bus *eventbus.Bus)
- func (s *Store) SetGraphHooks(hooks *GraphHooks)
- type TripleCallback
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildObservationTools ¶ added in v0.7.0
BuildObservationTools creates tools for observational memory management.
func CountMessageTokens ¶
CountMessageTokens returns the estimated token count for a single message.
func CountMessagesTokens ¶
CountMessagesTokens returns the total estimated token count for a batch of messages.
func EstimateTokens ¶
EstimateTokens delegates to types.EstimateTokens for token count approximation.
Types ¶
type Buffer ¶
type Buffer struct {
// contains filtered or unexported fields
}
Buffer manages background observation and reflection processing.
func NewBuffer ¶
func NewBuffer( observer *Observer, reflector *Reflector, store *Store, msgThreshold, obsThreshold int, getMessages MessageProvider, logger *zap.SugaredLogger, ) *Buffer
NewBuffer creates a new asynchronous observation buffer.
func (*Buffer) SetCompactor ¶
func (b *Buffer) SetCompactor(c MessageCompactor)
SetCompactor enables message compaction after observation. When set, observed messages are replaced with a summary message in the session, effectively reducing the session's memory footprint.
func (*Buffer) SetReflectionConsolidationThreshold ¶
SetReflectionConsolidationThreshold overrides the default number of reflections that must accumulate before meta-reflection (consolidation) is triggered.
func (*Buffer) Start ¶
Start launches the background goroutine. The WaitGroup is incremented so callers can wait for graceful shutdown.
type GraphHooks ¶
type GraphHooks struct {
// contains filtered or unexported fields
}
GraphHooks adds graph relationship tracking to the memory system. It generates triples for temporal ordering, session membership, and reflection-observation links.
func NewGraphHooks ¶
func NewGraphHooks(callback TripleCallback, logger *zap.SugaredLogger) *GraphHooks
NewGraphHooks creates a new graph hooks instance.
func (*GraphHooks) OnObservation ¶
func (h *GraphHooks) OnObservation(obs Observation, previousObsID string)
OnObservation generates graph triples when an observation is saved. Triples created:
- observation:ID --[in_session]--> session:SessionKey
- observation:ID --[follows]--> observation:PreviousID (if provided)
func (*GraphHooks) OnReflection ¶
func (h *GraphHooks) OnReflection(ref Reflection, observationIDs []string)
OnReflection generates graph triples when a reflection is saved. Triples created:
- reflection:ID --[in_session]--> session:SessionKey
- reflection:ID --[reflects_on]--> observation:ObsID (for each related observation)
type MessageCompactor ¶
MessageCompactor replaces observed messages with a summary to reduce session size.
type MessageProvider ¶
MessageProvider retrieves messages for a session key.
type Observation ¶
type Observation struct {
ID uuid.UUID
SessionKey string
Content string
TokenCount int
SourceStartIndex int
SourceEndIndex int
CreatedAt time.Time
}
Observation represents a compressed note from conversation history.
type Observer ¶
type Observer struct {
// contains filtered or unexported fields
}
Observer generates compressed observation notes from conversation history.
func NewObserver ¶
func NewObserver(generator llm.TextGenerator, store *Store, logger *zap.SugaredLogger) *Observer
NewObserver creates a new Observer.
func (*Observer) Observe ¶
func (o *Observer) Observe(ctx context.Context, sessionKey string, messages []session.Message, lastObservedIndex int) (*Observation, error)
Observe generates a compressed observation from un-observed messages. It takes messages from lastObservedIndex+1 onward, calls the LLM, and persists the result. Returns nil if there are no new messages to observe.
type Reflection ¶
type Reflection struct {
ID uuid.UUID
SessionKey string
Content string
TokenCount int
Generation int
CreatedAt time.Time
}
Reflection represents condensed observations.
type Reflector ¶
type Reflector struct {
// contains filtered or unexported fields
}
Reflector condenses accumulated observations into reflections.
func NewReflector ¶
func NewReflector(generator llm.TextGenerator, store *Store, logger *zap.SugaredLogger) *Reflector
NewReflector creates a new Reflector.
func (*Reflector) Reflect ¶
Reflect condenses all observations for a session into a single reflection. Returns nil if there are no observations to condense.
func (*Reflector) ReflectOnReflections ¶
func (r *Reflector) ReflectOnReflections(ctx context.Context, sessionKey string) (*Reflection, error)
ReflectOnReflections condenses accumulated reflections into a higher-generation reflection. Returns nil if there are no reflections to condense.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store provides CRUD operations for observations and reflections.
func NewStore ¶
func NewStore(client *ent.Client, logger *zap.SugaredLogger) *Store
NewStore creates a new observational memory store.
func (*Store) DeleteObservations ¶
DeleteObservations deletes observations by their IDs.
func (*Store) DeleteObservationsBySession ¶
DeleteObservationsBySession deletes all observations for a session.
func (*Store) DeleteReflections ¶
DeleteReflections deletes reflections by their IDs.
func (*Store) DeleteReflectionsBySession ¶
DeleteReflectionsBySession deletes all reflections for a session.
func (*Store) GetObservation ¶
GetObservation retrieves a single observation by its ID.
func (*Store) GetReflection ¶
GetReflection retrieves a single reflection by its ID.
func (*Store) ListObservations ¶
ListObservations returns observations for a session ordered by created_at ascending.
func (*Store) ListRecentObservations ¶
func (s *Store) ListRecentObservations(ctx context.Context, sessionKey string, limit int) ([]Observation, error)
ListRecentObservations returns the N most recent observations for a session. Results are ordered by created_at ascending (oldest first) for chronological display.
func (*Store) ListRecentReflections ¶
func (s *Store) ListRecentReflections(ctx context.Context, sessionKey string, limit int) ([]Reflection, error)
ListRecentReflections returns the N most recent reflections for a session. Results are ordered by created_at ascending (oldest first) for chronological display.
func (*Store) ListReflections ¶
ListReflections returns reflections for a session ordered by created_at ascending.
func (*Store) SaveObservation ¶
func (s *Store) SaveObservation(ctx context.Context, obs Observation) error
SaveObservation persists an observation to the database.
func (*Store) SaveReflection ¶
func (s *Store) SaveReflection(ctx context.Context, ref Reflection) error
SaveReflection persists a reflection to the database.
func (*Store) SetEventBus ¶ added in v0.7.0
SetEventBus sets the optional event bus for publishing content events.
func (*Store) SetGraphHooks ¶
func (s *Store) SetGraphHooks(hooks *GraphHooks)
SetGraphHooks sets the graph hooks for temporal/session triple generation.
type TripleCallback ¶
TripleCallback is a hook that receives graph triples for asynchronous storage.
Source Files