Documentation
¶
Overview ¶
Package agentmemory provides per-agent persistent memory.
Unlike the memory package (session-scoped observations), agentmemory stores entries that persist across sessions and are scoped by agent name. Each entry has a kind (Pattern, Preference, Fact, Skill) and a confidence score.
Memory scopes control visibility:
- Instance: visible only to one agent instance
- Type: visible to all instances of the same agent type
- Global: visible to all agents
Related packages:
- memory: session-scoped observational memory (temporal, ephemeral)
- knowledge: user-contributed knowledge store
- learning: feeds extracted patterns into agentmemory
Index ¶
- func BuildTools(store Store) []*agent.Tool
- type EntStore
- func (s *EntStore) Delete(agentName, key string) error
- func (s *EntStore) Get(agentName, key string) (*Entry, error)
- func (s *EntStore) IncrementUseCount(agentName, key string) error
- func (s *EntStore) ListAgentNames() ([]string, error)
- func (s *EntStore) ListAll(agentName string) ([]*Entry, error)
- func (s *EntStore) Prune(agentName string, minConfidence float64) (int, error)
- func (s *EntStore) Save(entry *Entry) error
- func (s *EntStore) Search(agentName string, opts SearchOptions) ([]*Entry, error)
- func (s *EntStore) SearchWithContext(agentName string, query string, limit int) ([]*Entry, error)
- func (s *EntStore) SearchWithContextOptions(agentName string, opts SearchOptions) ([]*Entry, error)
- type Entry
- type InMemoryStore
- func (s *InMemoryStore) Delete(agentName, key string) error
- func (s *InMemoryStore) Get(agentName, key string) (*Entry, error)
- func (s *InMemoryStore) IncrementUseCount(agentName, key string) error
- func (s *InMemoryStore) ListAgentNames() ([]string, error)
- func (s *InMemoryStore) ListAll(agentName string) ([]*Entry, error)
- func (s *InMemoryStore) Prune(agentName string, minConfidence float64) (int, error)
- func (s *InMemoryStore) Save(entry *Entry) error
- func (s *InMemoryStore) Search(agentName string, opts SearchOptions) ([]*Entry, error)
- func (s *InMemoryStore) SearchWithContext(agentName string, query string, limit int) ([]*Entry, error)
- func (s *InMemoryStore) SearchWithContextOptions(agentName string, opts SearchOptions) ([]*Entry, error)
- type MemoryKind
- type MemoryScope
- type SearchOptions
- type Store
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildTools ¶ added in v0.7.0
BuildTools creates tools that let agents save, recall, and forget their own persistent memories (patterns, preferences, facts, skills).
Types ¶
type EntStore ¶ added in v0.7.0
type EntStore struct {
// contains filtered or unexported fields
}
EntStore is a persistent Ent-backed implementation of Store.
func NewEntStore ¶ added in v0.7.0
NewEntStore creates a new Ent-backed agent memory store.
func (*EntStore) IncrementUseCount ¶ added in v0.7.0
func (*EntStore) ListAgentNames ¶ added in v0.7.0
func (*EntStore) ListAll ¶ added in v0.7.0
ListAll returns all entries for a given agent, sorted by updated_at DESC.
func (*EntStore) Search ¶ added in v0.7.0
func (s *EntStore) Search(agentName string, opts SearchOptions) ([]*Entry, error)
func (*EntStore) SearchWithContext ¶ added in v0.7.0
SearchWithContext resolves entries with scope fallback: Phase 1 = agent's all entries (any scope), Phase 2 = other agents' global only. Phase 1 sorted first, Phase 2 after, then global limit.
NOTE: type scope not yet implemented — only instance and global scopes are considered. Type scope entries are skipped during context resolution.
func (*EntStore) SearchWithContextOptions ¶ added in v0.7.0
func (s *EntStore) SearchWithContextOptions(agentName string, opts SearchOptions) ([]*Entry, error)
SearchWithContextOptions is like SearchWithContext but accepts full SearchOptions (Kind, Tags, MinConfidence). Filters are applied during collection, before limit truncation, so no results are lost.
NOTE: type scope not yet implemented — only instance and global scopes are considered. Type scope entries are skipped during context resolution.
type Entry ¶
type Entry struct {
ID string `json:"id"`
AgentName string `json:"agent_name"`
Scope MemoryScope `json:"scope"`
Kind MemoryKind `json:"kind"`
Key string `json:"key"`
Content string `json:"content"`
Confidence float64 `json:"confidence"` // 0.0-1.0
UseCount int `json:"use_count"`
Tags []string `json:"tags,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
Entry represents a single agent memory entry.
type InMemoryStore ¶
type InMemoryStore struct {
// contains filtered or unexported fields
}
InMemoryStore is a thread-safe in-memory implementation of Store.
func NewInMemoryStore ¶
func NewInMemoryStore() *InMemoryStore
NewInMemoryStore creates a new in-memory agent memory store.
func (*InMemoryStore) Delete ¶
func (s *InMemoryStore) Delete(agentName, key string) error
func (*InMemoryStore) IncrementUseCount ¶
func (s *InMemoryStore) IncrementUseCount(agentName, key string) error
func (*InMemoryStore) ListAgentNames ¶
func (s *InMemoryStore) ListAgentNames() ([]string, error)
func (*InMemoryStore) Prune ¶
func (s *InMemoryStore) Prune(agentName string, minConfidence float64) (int, error)
func (*InMemoryStore) Save ¶
func (s *InMemoryStore) Save(entry *Entry) error
func (*InMemoryStore) Search ¶
func (s *InMemoryStore) Search(agentName string, opts SearchOptions) ([]*Entry, error)
func (*InMemoryStore) SearchWithContext ¶
func (*InMemoryStore) SearchWithContextOptions ¶ added in v0.7.0
func (s *InMemoryStore) SearchWithContextOptions(agentName string, opts SearchOptions) ([]*Entry, error)
type MemoryKind ¶
type MemoryKind string
MemoryKind categorizes memory entries.
const ( KindPattern MemoryKind = "pattern" // learned tool usage patterns KindPreference MemoryKind = "preference" // user/agent preferences KindFact MemoryKind = "fact" // discovered facts KindSkill MemoryKind = "skill" // learned capabilities )
func (MemoryKind) Valid ¶ added in v0.7.0
func (k MemoryKind) Valid() bool
Valid returns true if k is one of the defined MemoryKind constants.
type MemoryScope ¶
type MemoryScope string
MemoryScope defines the visibility of a memory entry.
const ( ScopeInstance MemoryScope = "instance" // specific to one agent instance ScopeType MemoryScope = "type" // shared across agents of same type ScopeGlobal MemoryScope = "global" // shared across all agents )
type SearchOptions ¶
type SearchOptions struct {
Query string
Scope MemoryScope
Kind MemoryKind
Tags []string
MinConfidence float64
Limit int
}
SearchOptions configures a memory search query.
type Store ¶
type Store interface {
// Save upserts a memory entry (matched by agent_name + key).
Save(entry *Entry) error
// Get retrieves a specific entry by agent name and key.
Get(agentName, key string) (*Entry, error)
// Search finds entries matching criteria.
Search(agentName string, opts SearchOptions) ([]*Entry, error)
// SearchWithContext resolves entries with scope fallback:
// instance (agent_name) > type (all agents of same type) > global.
SearchWithContext(agentName string, query string, limit int) ([]*Entry, error)
// SearchWithContextOptions is like SearchWithContext but accepts full
// SearchOptions (Kind, Tags, MinConfidence). Filters are applied during
// collection, before limit truncation, so no results are lost.
SearchWithContextOptions(agentName string, opts SearchOptions) ([]*Entry, error)
// Delete removes an entry.
Delete(agentName, key string) error
// IncrementUseCount bumps the use counter for an entry.
IncrementUseCount(agentName, key string) error
// Prune removes entries below a confidence threshold.
Prune(agentName string, minConfidence float64) (int, error)
// ListAgentNames returns the names of all agents that have stored memories.
ListAgentNames() ([]string, error)
// ListAll returns all entries for a given agent.
ListAll(agentName string) ([]*Entry, error)
}
Store is the interface for agent memory storage.
Source Files