memory

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Jul 14, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EnsureDirectory

func EnsureDirectory() error

EnsureDirectory ensures the memory directory exists

Types

type Catalog

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

Catalog stores searchable runtime memory entries and learned tool usage.

func NewCatalog

func NewCatalog() *Catalog

NewCatalog creates a searchable memory catalog with default configuration.

func NewCatalogWithConfig

func NewCatalogWithConfig(config *MemoryConfig) *Catalog

NewCatalogWithConfig creates a searchable memory catalog with custom configuration.

func (*Catalog) CleanupExpired

func (ms *Catalog) CleanupExpired() int

CleanupExpired removes expired memory entries

func (*Catalog) DeleteEntry

func (ms *Catalog) DeleteEntry(id string) error

DeleteEntry removes a single entry by ID.

func (*Catalog) Entries

func (ms *Catalog) Entries() []Entry

Entries returns a snapshot of the current catalog entries.

func (*Catalog) Export

func (ms *Catalog) Export() ([]byte, error)

Export exports all entries as JSON.

func (*Catalog) GetEntry

func (ms *Catalog) GetEntry(id string) (*Entry, error)

GetEntry returns a single entry by ID and updates its access metadata.

func (*Catalog) GetToolUsagePatterns

func (ms *Catalog) GetToolUsagePatterns(toolName string) (*ToolUsageMemory, error)

GetToolUsagePatterns returns learned usage for one tool.

func (*Catalog) Import

func (ms *Catalog) Import(data []byte) error

Import imports entries from JSON.

func (*Catalog) LearnToolUsage

func (ms *Catalog) LearnToolUsage(toolName string, parameters map[string]any, success bool, err error) error

LearnToolUsage learns from tool execution.

func (*Catalog) ResetEntries

func (ms *Catalog) ResetEntries(entries []Entry)

ResetEntries replaces catalog entries with a provided snapshot.

func (*Catalog) ResetToolUsage

func (ms *Catalog) ResetToolUsage(toolUsage map[string]*ToolUsageMemory)

ResetToolUsage replaces the learned tool usage state.

func (*Catalog) Search

func (ms *Catalog) Search(query MemoryQuery) (*MemorySearchResult, error)

Search retrieves memories based on the provided query.

func (*Catalog) Start

func (ms *Catalog) Start()

Start starts background cleanup for the catalog.

func (*Catalog) Stats

func (ms *Catalog) Stats() MemoryStats

Stats returns current memory statistics.

func (*Catalog) Stop

func (ms *Catalog) Stop()

Stop stops background cleanup for the catalog.

func (*Catalog) StoreEntry

func (ms *Catalog) StoreEntry(entry Entry) error

StoreEntry stores a new memory entry

func (*Catalog) ToolUsageSnapshot

func (ms *Catalog) ToolUsageSnapshot() map[string]*ToolUsageMemory

ToolUsageSnapshot returns a deep copy of learned tool usage patterns.

type ContextBuilder

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

ContextBuilder builds context from learned patterns

func NewContextBuilder

func NewContextBuilder(projectPath string) (*ContextBuilder, error)

NewContextBuilder creates a new context builder

func (*ContextBuilder) Build

func (b *ContextBuilder) Build() string

Build returns learned context for prompts

type CrossSession

type CrossSession struct {
	SessionSummaries map[string]*SessionSummary `json:"session_summaries"` // SessionID -> Summary
	GlobalPatterns   map[string]*PatternEntry   `json:"global_patterns"`   // Key -> Pattern
	LoadedAt         time.Time                  `json:"loaded_at"`
}

CrossSession holds cross-session memory

func NewCrossSession

func NewCrossSession() *CrossSession

NewCrossSession creates new cross-session memory

type Duration

type Duration struct {
	MS int64 `json:"ms"`
}

Duration is a simple duration wrapper for JSON

type Entry

type Entry struct {
	ID         string         `json:"id"`
	Scope      MemoryScope    `json:"scope"`
	Type       MemoryType     `json:"type"`
	Key        string         `json:"key"` // Unique key for deduplication
	Value      string         `json:"value"`
	Source     string         `json:"source"`     // Where this was learned
	Confidence float64        `json:"confidence"` // 0-1, how confident we are
	CreatedAt  time.Time      `json:"created_at"`
	UpdatedAt  time.Time      `json:"updated_at"`
	Metadata   *EntryMetadata `json:"metadata,omitempty"`

	// Advanced features from agent system
	Content      string     `json:"content"`              // Full content (expanded from Value)
	Tags         []string   `json:"tags"`                 // Categorization tags
	Importance   float64    `json:"importance"`           // 0-1, importance score
	AccessCount  int        `json:"access_count"`         // Access tracking
	LastAccessed time.Time  `json:"last_accessed"`        // Last access time
	ExpiresAt    *time.Time `json:"expires_at,omitempty"` // Optional expiration
	SessionID    string     `json:"session_id,omitempty"` // Optional session context
}

Entry represents a single memory entry

func NewEntry

func NewEntry(scope MemoryScope, memType MemoryType, key, value, source string) *Entry

NewEntry creates a new memory entry

type EntryMetadata

type EntryMetadata struct {
	FilePath    string     `json:"file_path,omitempty"`
	LineNumber  int        `json:"line_number,omitempty"`
	ToolUsed    string     `json:"tool_used,omitempty"`
	Frequency   int        `json:"frequency"` // How many times used
	LastUsedAt  *time.Time `json:"last_used_at,omitempty"`
	SuccessRate float64    `json:"success_rate"` // 0-1
	Tags        []string   `json:"tags,omitempty"`
}

EntryMetadata contains additional entry metadata

type ErrorLearner

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

ErrorLearner learns from errors

func NewErrorLearner

func NewErrorLearner(projectPath string) (*ErrorLearner, error)

NewErrorLearner creates a new error learner

func (*ErrorLearner) OnError

func (e *ErrorLearner) OnError(err error) error

OnError learns from an error

type ErrorPattern

type ErrorPattern struct {
	ErrorType  string    `json:"error_type"`
	Message    string    `json:"message"`
	Suggestion string    `json:"suggestion"`
	Frequency  int       `json:"frequency"`
	FirstSeen  time.Time `json:"first_seen"`
	LastSeen   time.Time `json:"last_seen"`
}

ErrorPattern represents a learned error pattern

type FileStore

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

FileStore implements Store using JSON files

func NewFileStore

func NewFileStore(basePath string) (*FileStore, error)

NewFileStore creates a new file store

func (*FileStore) LoadCrossSession

func (s *FileStore) LoadCrossSession() (*CrossSession, error)

LoadCrossSession loads cross-session memory

func (*FileStore) LoadProjectMemory

func (s *FileStore) LoadProjectMemory(projectPath string) (*ProjectMemory, error)

LoadProjectMemory loads project-specific memory

func (*FileStore) LoadUserMemory

func (s *FileStore) LoadUserMemory() (*UserMemory, error)

LoadUserMemory loads user-wide memory

func (*FileStore) SaveCrossSession

func (s *FileStore) SaveCrossSession(m *CrossSession) error

SaveCrossSession saves cross-session memory

func (*FileStore) SaveProjectMemory

func (s *FileStore) SaveProjectMemory(m *ProjectMemory) error

SaveProjectMemory saves project memory

func (*FileStore) SaveUserMemory

func (s *FileStore) SaveUserMemory(m *UserMemory) error

SaveUserMemory saves user memory

type IntegrationManager

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

IntegrationManager provides a unified interface to the catalog-backed and manager-backed memory layers.

func NewIntegrationManager

func NewIntegrationManager(enableCatalog bool) (*IntegrationManager, error)

NewIntegrationManager creates a new integration manager

func (*IntegrationManager) Context

func (im *IntegrationManager) Context() string

Context returns memory context for inclusion in LLM prompts

func (*IntegrationManager) DisableCatalog

func (im *IntegrationManager) DisableCatalog()

DisableCatalog switches back to manager-backed memory mode.

func (*IntegrationManager) EnableCatalog

func (im *IntegrationManager) EnableCatalog()

EnableCatalog switches to catalog-backed memory mode.

func (*IntegrationManager) ExportAll

func (im *IntegrationManager) ExportAll() (map[string][]byte, error)

ExportAll exports all memory from all systems

func (*IntegrationManager) GetPreferences

func (im *IntegrationManager) GetPreferences(scope MemoryScope) []*Entry

GetPreferences retrieves preferences for a scope

func (*IntegrationManager) GetToolUsagePatterns

func (im *IntegrationManager) GetToolUsagePatterns(toolName string) (*ToolUsageMemory, error)

GetToolUsagePatterns retrieves tool usage patterns

func (*IntegrationManager) IsCatalogMode

func (im *IntegrationManager) IsCatalogMode() bool

IsCatalogMode returns whether catalog-backed memory is enabled.

func (*IntegrationManager) LearnToolUsage

func (im *IntegrationManager) LearnToolUsage(toolName string, parameters map[string]any, success bool, err error) error

LearnToolUsage learns from tool execution.

func (*IntegrationManager) Search

Search performs intelligent search across memory systems

func (*IntegrationManager) Start

func (im *IntegrationManager) Start() error

Start starts the catalog-backed layer when enabled.

func (*IntegrationManager) Stats

func (im *IntegrationManager) Stats() map[string]interface{}

Stats returns combined statistics from both layers.

func (*IntegrationManager) Stop

func (im *IntegrationManager) Stop()

Stop stops the catalog-backed layer when enabled.

func (*IntegrationManager) StorePreference

func (im *IntegrationManager) StorePreference(scope MemoryScope, key, value, source string) error

StorePreference stores a user preference

type Learner

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

Learner learns patterns from tool usage and results

func NewLearner

func NewLearner(projectPath, sessionID string) (*Learner, error)

NewLearner creates a new auto-learner

func (*Learner) AddInstruction

func (l *Learner) AddInstruction(key, instruction, source string) error

AddInstruction learns a persistent instruction

func (*Learner) AddUserPreference

func (l *Learner) AddUserPreference(key, value, source string) error

AddUserPreference learns a user preference

func (*Learner) Flush

func (l *Learner) Flush() error

Flush saves learned patterns to storage

func (*Learner) OnToolUse

func (l *Learner) OnToolUse(toolName string, success bool, durationMs int, errMsg string)

OnToolUse records a tool usage attempt

type Manager

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

Manager manages all memory types

func NewManager

func NewManager() (*Manager, error)

NewManager creates a new memory manager

func NewManagerWithPath

func NewManagerWithPath(basePath string) (*Manager, error)

NewManagerWithPath creates a memory manager with explicit path

func NewService

func NewService() (*Manager, error)

func NewServiceWithPath

func NewServiceWithPath(basePath string) (*Manager, error)

func (*Manager) AddSessionSummary

func (m *Manager) AddSessionSummary(sessionID, projectPath, summary string, toolsUsed []string) error

AddSessionSummary adds a session summary for cross-session recall

func (*Manager) Catalog

func (m *Manager) Catalog() *Catalog

func (*Manager) Context

func (m *Manager) Context() string

Context returns memory context for inclusion in LLM prompts

func (*Manager) DeleteEntry

func (m *Manager) DeleteEntry(id string) error

func (*Manager) GetCrossSession

func (m *Manager) GetCrossSession() *CrossSession

GetCrossSession returns the cross-session memory

func (*Manager) GetEntry

func (m *Manager) GetEntry(id string) (*Entry, error)

func (*Manager) GetPreferences

func (m *Manager) GetPreferences(scope MemoryScope) []*Entry

GetPreferences retrieves preferences for a scope

func (*Manager) GetProject

func (m *Manager) GetProject() *ProjectMemory

GetProject returns the current project memory

func (*Manager) GetProjectHistory

func (m *Manager) GetProjectHistory(projectPath string) []*SessionSummary

GetProjectHistory retrieves past session summaries for a project

func (*Manager) GetToolUsagePatterns

func (m *Manager) GetToolUsagePatterns(toolName string) (*ToolUsageMemory, error)

func (*Manager) GetUser

func (m *Manager) GetUser() *UserMemory

GetUser returns the current user memory

func (*Manager) LearnInstruction

func (m *Manager) LearnInstruction(scope MemoryScope, key, value, source string) error

LearnInstruction adds a learned persistent instruction.

func (*Manager) LearnPreference

func (m *Manager) LearnPreference(scope MemoryScope, key, value, source string) error

LearnPreference adds a learned preference

func (*Manager) LearnToolUsage

func (m *Manager) LearnToolUsage(toolName string, parameters map[string]any, success bool, err error) error

func (*Manager) LoadAll

func (m *Manager) LoadAll(projectPath string) error

LoadAll loads all memory types

func (*Manager) LoadCrossSession

func (m *Manager) LoadCrossSession() error

LoadCrossSession loads cross-session memory

func (*Manager) LoadProject

func (m *Manager) LoadProject(projectPath string) error

LoadProject loads project memory

func (*Manager) LoadUser

func (m *Manager) LoadUser() error

LoadUser loads user memory

func (*Manager) SaveAll

func (m *Manager) SaveAll() error

SaveAll saves all memory types

func (*Manager) SaveCrossSession

func (m *Manager) SaveCrossSession() error

SaveCrossSession saves cross-session memory

func (*Manager) SaveProject

func (m *Manager) SaveProject() error

SaveProject saves project memory

func (*Manager) SaveUser

func (m *Manager) SaveUser() error

SaveUser saves user memory

func (*Manager) Search

func (m *Manager) Search(query MemoryQuery) (*MemorySearchResult, error)

Search looks up entries in the central searchable catalog.

func (*Manager) Stats

func (m *Manager) Stats() MemoryStats

func (*Manager) StoreEntry

func (m *Manager) StoreEntry(entry Entry) error

StoreEntry stores an entry in the central catalog and persists scoped entries when possible.

type MemoryConfig

type MemoryConfig struct {
	MaxEntries           int                   `json:"max_entries"`
	DefaultTTL           time.Duration         `json:"default_ttl"`
	LearningEnabled      bool                  `json:"learning_enabled"`
	ImportanceDecay      float64               `json:"importance_decay"` // 0-1, per access
	MinImportance        float64               `json:"min_importance"`
	MaxImportance        float64               `json:"max_importance"`
	EnableSemanticSearch bool                  `json:"enable_semantic_search"`
	IndexingEnabled      bool                  `json:"indexing_enabled"`
	RetentionPolicy      MemoryRetentionPolicy `json:"retention_policy"`
}

MemoryConfig configures memory system behavior

func DefaultMemoryConfig

func DefaultMemoryConfig() *MemoryConfig

DefaultMemoryConfig returns default memory configuration

type MemoryIndex

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

MemoryIndex provides fast searching capabilities

type MemoryQuery

type MemoryQuery struct {
	Types         []MemoryType `json:"types"`                // Filter by types
	Content       string       `json:"content"`              // Search in content
	Tags          []string     `json:"tags,omitempty"`       // Filter by tags
	MinImportance float64      `json:"min_importance"`       // Filter by minimum importance
	MinConfidence float64      `json:"min_confidence"`       // Filter by minimum confidence
	SessionID     string       `json:"session_id"`           // Filter by session
	Tool          string       `json:"tool"`                 // Filter by tool name
	Keywords      []string     `json:"keywords"`             // Specific keywords to match
	ExactMatch    bool         `json:"exact_match"`          // Require exact match
	TimeRange     *TimeRange   `json:"time_range,omitempty"` // Filter by time range
	Limit         int          `json:"limit"`                // Maximum results
}

MemoryQuery represents a query for memory retrieval

type MemoryRetentionPolicy

type MemoryRetentionPolicy struct {
	ToolUsageRetention    time.Duration `json:"tool_usage_retention"`
	ConversationRetention time.Duration `json:"conversation_retention"`
	ErrorRetention        time.Duration `json:"error_retention"`
	ContextRetention      time.Duration `json:"context_retention"`
	SuccessRetention      time.Duration `json:"success_retention"`
}

MemoryRetentionPolicy defines type-specific retention windows.

type MemoryScope

type MemoryScope string

MemoryScope represents the scope of memory

const (
	MemoryScopeProject MemoryScope = "project" // Per project (.seshat/)
	MemoryScopeUser    MemoryScope = "user"    // Global user (~/.seshat/)
	MemoryScopeSession MemoryScope = "session" // Current session
)

type MemorySearchResult

type MemorySearchResult struct {
	Entries       []Entry       `json:"entries"`       // Found entries
	Total         int           `json:"total"`         // Total matches
	Query         MemoryQuery   `json:"query"`         // Executed query
	ExecutionTime time.Duration `json:"executionTime"` // Search duration
}

MemorySearchResult represents search results

type MemoryStats

type MemoryStats struct {
	TotalEntries         int                `json:"total_entries"`
	EntriesByType        map[MemoryType]int `json:"entries_by_type"`
	TotalQueries         int64              `json:"total_queries"`
	SuccessfulRetrievals int64              `json:"successful_retrievals"`
	MissedRetrievals     int64              `json:"missed_retrievals"`
	QueryLatency         time.Duration      `json:"query_latency"`
	StorageSize          int64              `json:"storage_size"` // bytes
	AverageImportance    float64            `json:"average_importance"`
	AverageConfidence    float64            `json:"average_confidence"`
	TotalAccessCount     int64              `json:"total_access_count"`
	MostAccessed         []string           `json:"most_accessed"`
	OldestEntry          *time.Time         `json:"oldest_entry,omitempty"`
	NewestEntry          *time.Time         `json:"newest_entry,omitempty"`
}

MemoryStats tracks memory system statistics

type MemoryType

type MemoryType string

MemoryType represents the type of memory

const (
	MemoryTypePreference  MemoryType = "preference"  // User preferences
	MemoryTypeInstruction MemoryType = "instruction" // Custom instructions
	MemoryTypePattern     MemoryType = "pattern"     // Learned patterns
	MemoryTypeSummary     MemoryType = "summary"     // Session summary
	MemoryTypeKnowledge   MemoryType = "knowledge"   // Project knowledge

	// Advanced types from agent system
	MemoryTypeToolUsage    MemoryType = "tool_usage"   // Learned patterns from tool usage
	MemoryTypeConversation MemoryType = "conversation" // Conversation context and patterns
	MemoryTypeError        MemoryType = "error"        // Learned error patterns and solutions
	MemoryTypeContext      MemoryType = "context"      // Situational context memory
	MemoryTypeSuccess      MemoryType = "success"      // Successful patterns and approaches
)

type ParameterPattern

type ParameterPattern struct {
	Parameters map[string]any `json:"parameters"`
	Frequency  int            `json:"frequency"`
	Success    bool           `json:"success"`
	LastUsed   *time.Time     `json:"last_used,omitempty"`
}

ParameterPattern represents a specific parameter pattern

type PatternEntry

type PatternEntry struct {
	Key         string    `json:"key"`
	Pattern     string    `json:"pattern"`
	Description string    `json:"description"`
	Frequency   int       `json:"frequency"`
	SuccessRate float64   `json:"success_rate"`
	LastSeenAt  time.Time `json:"last_seen_at"`
	Examples    []string  `json:"examples"`
}

PatternEntry represents a learned pattern

type ProjectConfig

type ProjectConfig struct {
	Enabled           bool     `json:"enabled"`
	AutoLearnPatterns bool     `json:"auto_learn_patterns"`
	MaxEntries        int      `json:"max_entries"`
	RetentionDays     int      `json:"retention_days"`
	IncludePatterns   []string `json:"include_patterns,omitempty"`
	ExcludePatterns   []string `json:"exclude_patterns,omitempty"`
}

ProjectConfig holds project memory configuration

func DefaultProjectConfig

func DefaultProjectConfig() *ProjectConfig

DefaultProjectConfig returns default project memory config

type ProjectMemory

type ProjectMemory struct {
	ProjectPath string                      `json:"project_path"`
	RootID      string                      `json:"root_id"` // Root dir ID (git repo or hash)
	Entries     map[string]*Entry           `json:"entries"` // Key -> Entry
	ToolUsage   map[string]*ToolUsageMemory `json:"tool_usage,omitempty"`
	Config      *ProjectConfig              `json:"config"`
	LoadedAt    time.Time                   `json:"loaded_at"`
}

ProjectMemory holds project-specific memory

func NewProjectMemory

func NewProjectMemory(projectPath string) *ProjectMemory

NewProjectMemory creates new project memory

type Service

type Service = Manager

Service is the central memory service used by the engine runtime.

type SessionSummary

type SessionSummary struct {
	SessionID         string    `json:"session_id"`
	ProjectPath       string    `json:"project_path"`
	Summary           string    `json:"summary"`
	ToolsUsed         []string  `json:"tools_used"`
	KeyLearned        []string  `json:"key_learned"`
	ErrorsEncountered []string  `json:"errors_encountered"`
	CompletedAt       time.Time `json:"completed_at"`
}

SessionSummary is a summary of a past session

type Store

type Store interface {
	LoadProjectMemory(projectPath string) (*ProjectMemory, error)
	SaveProjectMemory(m *ProjectMemory) error
	LoadUserMemory() (*UserMemory, error)
	SaveUserMemory(m *UserMemory) error
	LoadCrossSession() (*CrossSession, error)
	SaveCrossSession(m *CrossSession) error
}

Store interface for memory persistence

type TimeRange

type TimeRange struct {
	Start time.Time `json:"start"`
	End   time.Time `json:"end"`
}

TimeRange represents a time range for filtering memory entries.

type ToolStats

type ToolStats struct {
	ToolName    string    `json:"tool_name"`
	Attempts    int       `json:"attempts"`
	Successes   int       `json:"successes"`
	Failures    int       `json:"failures"`
	LastUsedAt  time.Time `json:"last_used_at"`
	AvgDuration Duration  `json:"avg_duration_ms"`
}

ToolStats tracks tool usage statistics

type ToolUsageMemory

type ToolUsageMemory struct {
	ToolName             string             `json:"tool_name"`
	SuccessfulParameters []ParameterPattern `json:"successful_parameters"`
	FailedParameters     []ParameterPattern `json:"failed_parameters"`
	TypicalUsage         string             `json:"typical_usage"`
	SuccessRate          float64            `json:"success_rate"`
	UsageCount           int                `json:"usage_count"`
	LastUsed             time.Time          `json:"last_used"`
}

ToolUsageMemory tracks usage patterns for a tool

type UserConfig

type UserConfig struct {
	Enabled           bool `json:"enabled"`
	AutoLearnPatterns bool `json:"auto_learn_patterns"`
	MaxEntries        int  `json:"max_entries"`
	ShareWithProjects bool `json:"share_with_projects"`
}

UserConfig holds user memory configuration

func DefaultUserConfig

func DefaultUserConfig() *UserConfig

DefaultUserConfig returns default user memory config

type UserMemory

type UserMemory struct {
	UserID   string            `json:"user_id"`
	Entries  map[string]*Entry `json:"entries"`
	Config   *UserConfig       `json:"config"`
	LoadedAt time.Time         `json:"loaded_at"`
}

UserMemory holds user-wide memory

func NewUserMemory

func NewUserMemory(userID string) *UserMemory

NewUserMemory creates new user memory

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL