memory

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Apr 15, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNotFound is returned when a memory entry doesn't exist.
	ErrNotFound = errors.New("memory: entry not found")
)

Functions

func FormatFrontmatter 

func FormatFrontmatter(meta map[string]string) string

FormatFrontmatter builds YAML frontmatter from a key-value map. Output: "---\nkey: \"value\"\n---\n"

func FormatMessageBlock 

func FormatMessageBlock(role, content, timestamp string) string

FormatMessageBlock creates a markdown section for one message. Output: "\n## [timestamp] role\n\ncontent\n"

func FormatSummaryFrontmatter 

func FormatSummaryFrontmatter(sessionID string, sourceMessageCount int) map[string]string

FormatSummaryFrontmatter builds frontmatter for a summary file.

func ParseFrontmatter 

func ParseFrontmatter(data []byte) (map[string]string, []byte, error)

ParseFrontmatter splits raw file content into frontmatter metadata and body. Returns (metadata map, body bytes, error). If no frontmatter found, returns empty meta and full body.

func ParseMessageBlocks 

func ParseMessageBlocks(body []byte) []agent.Message

ParseMessageBlocks extracts messages from the body section. Parses "## [timestamp] role" headings followed by content. Returns []agent.Message.

func ScopeWithMemory 

func ScopeWithMemory(ctx context.Context, scope MemoryScope) context.Context

ScopeWithMemory adds memory scope to context.

Types

type AsyncEmbeddingIndexer 

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

AsyncEmbeddingIndexer generates embeddings for new messages and stores them in the vector database asynchronously (fire-and-forget). If vectorStore or embeddingSvc is nil, indexing is silently skipped.

func NewAsyncEmbeddingIndexer 

func NewAsyncEmbeddingIndexer(embeddingSvc *EmbeddingService, vectorStore VectorStore) *AsyncEmbeddingIndexer

NewAsyncEmbeddingIndexer creates a new async embedding indexer.

func (*AsyncEmbeddingIndexer) OnMessage 

func (idx *AsyncEmbeddingIndexer) OnMessage(ctx context.Context, msg agent.SessionMessage)

OnMessage triggers async embedding generation and storage after a message is appended. This is fire-and-forget: errors are logged but never block the caller.

type ConversationSummarizer 

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

ConversationSummarizer generates session summaries using an LLM.

func NewConversationSummarizer 

func NewConversationSummarizer(store agent.ConversationStore, router providers.ModelRouter, threshold int) *ConversationSummarizer

NewConversationSummarizer creates a summarizer that triggers after threshold messages.

func (*ConversationSummarizer) CheckAndSummarize 

func (s *ConversationSummarizer) CheckAndSummarize(ctx context.Context, tenantID, userID, sessionID string)

CheckAndSummarize checks if a session exceeds the message threshold and generates a summary. Bounded by the context timeout set by the caller.

type DeleteFilter 

type DeleteFilter struct {
	TenantID  string
	SessionID string // optional
	Before    time.Time
}

DeleteFilter specifies which documents to delete.

type EmbeddingService 

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

EmbeddingService generates vector embeddings via ModelProvider. It routes embedding requests through the ModelRouter to find a provider that supports the CapEmbedding capability.

func NewEmbeddingService 

func NewEmbeddingService(router providers.ModelRouter, model string, dimensions int) *EmbeddingService

NewEmbeddingService creates a new embedding service.

func (*EmbeddingService) Embed 

func (s *EmbeddingService) Embed(ctx context.Context, text string) ([]float32, error)

Embed generates a vector embedding for a single text.

func (*EmbeddingService) EmbedBatch 

func (s *EmbeddingService) EmbedBatch(ctx context.Context, texts []string) ([][]float32, error)

EmbedBatch generates vector embeddings for multiple texts in a single API call.

type Entry 

type Entry struct {
	ID        string
	SessionID string
	Content   string
	Tags      []string
	CreatedAt time.Time
	TTL       time.Duration
}

Entry represents a short-term memory item.

type InMemoryStore 

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

InMemoryStore implements ShortTermStore using an in-memory map.

func NewInMemoryStore 

func NewInMemoryStore() *InMemoryStore

NewInMemoryStore creates a new in-memory store.

func (*InMemoryStore) ClearSession 

func (s *InMemoryStore) ClearSession(ctx context.Context, sessionID string) error

ClearSession removes all entries for a session.

func (*InMemoryStore) Delete 

func (s *InMemoryStore) Delete(ctx context.Context, id string) error

Delete removes a memory entry.

func (*InMemoryStore) ListBySession 

func (s *InMemoryStore) ListBySession(ctx context.Context, sessionID string) ([]Entry, error)

ListBySession returns all entries for a session.

func (*InMemoryStore) Retrieve 

func (s *InMemoryStore) Retrieve(ctx context.Context, id string) (*Entry, error)

Retrieve gets a memory entry by ID.

func (*InMemoryStore) Store 

func (s *InMemoryStore) Store(ctx context.Context, entry Entry) error

Store saves a memory entry.

type MarkdownCheckpoint 

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

MarkdownCheckpoint implements loop.Checkpoint using markdown files. Each task gets its own file: {dataDir}/checkpoints/task_{index}.md The latest state is also mirrored to latest.md for quick access.

func NewMarkdownCheckpoint 

func NewMarkdownCheckpoint(dataDir string) *MarkdownCheckpoint

NewMarkdownCheckpoint creates a checkpoint store under the given data directory.

func (*MarkdownCheckpoint) Save 

func (c *MarkdownCheckpoint) Save(ctx context.Context, taskIndex int, taskResult *loop.TaskResult, metrics *loop.LoopMetrics) error

Save persists the task execution state as a markdown file.

type MarkdownMemoryBridge 

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

MarkdownMemoryBridge wraps MarkdownMemoryStore to implement abstraction.MemoryManager. When vectorStore + embeddingSvc are configured, RetrieveSimilar uses semantic vector search and falls back to keyword matching on failure. Without vector config, pure keyword matching. This is the markdown-first bridge between core's memory abstraction and runtime's storage.

Design note: RetrieveByTag falls back to content-substring matching because the underlying MarkdownMemoryStore does not store structured tags per message. Full tag-based retrieval requires the vector layer (Phase 3.1).

func NewMarkdownMemoryBridge 

func NewMarkdownMemoryBridge(store *MarkdownMemoryStore, summarizer *ConversationSummarizer) *MarkdownMemoryBridge

NewMarkdownMemoryBridge creates a bridge from MarkdownMemoryStore to MemoryManager.

func (*MarkdownMemoryBridge) Forget 

func (b *MarkdownMemoryBridge) Forget(_ context.Context, _ string) error

Forget removes a specific memory entry. Markdown store is append-only — individual message deletion is not supported.

func (*MarkdownMemoryBridge) RetrieveByTag 

func (b *MarkdownMemoryBridge) RetrieveByTag(ctx context.Context, tags []string, limit int) ([]abstraction.MemoryEntry, error)

RetrieveByTag performs a best-effort scan of session history for tag matches. Requires ALL tags to be present in the message content (AND semantics). Falls back to content-substring matching since MarkdownMemoryStore does not store structured tags per message.

func (*MarkdownMemoryBridge) RetrieveSimilar 

func (b *MarkdownMemoryBridge) RetrieveSimilar(ctx context.Context, query string, limit int) ([]abstraction.MemoryEntry, error)

RetrieveSimilar performs semantic search against the vector store if configured, falling back to keyword-based matching against session history.

func (*MarkdownMemoryBridge) SetEmbeddingService 

func (b *MarkdownMemoryBridge) SetEmbeddingService(es *EmbeddingService)

SetEmbeddingService configures an optional embedding service for vector generation.

func (*MarkdownMemoryBridge) SetVectorStore 

func (b *MarkdownMemoryBridge) SetVectorStore(vs VectorStore)

SetVectorStore configures an optional vector store for semantic search.

func (*MarkdownMemoryBridge) StoreLongTerm 

func (b *MarkdownMemoryBridge) StoreLongTerm(ctx context.Context, entry abstraction.MemoryEntry) error

StoreLongTerm saves an entry as a session summary in the markdown store.

func (*MarkdownMemoryBridge) StoreShortTerm 

func (b *MarkdownMemoryBridge) StoreShortTerm(ctx context.Context, entry abstraction.MemoryEntry) error

StoreShortTerm saves a conversation-scoped entry to the markdown store.

func (*MarkdownMemoryBridge) Summarize 

func (b *MarkdownMemoryBridge) Summarize(ctx context.Context, entries []abstraction.MemoryEntry) (abstraction.MemoryEntry, error)

Summarize produces a summary from the given entries. If the summarizer (LLM-based) is available, it is used for real summarization. Otherwise, falls back to concatenation with rune-safe truncation.

type MarkdownMemoryStore 

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

MarkdownMemoryStore implements agent.ConversationStore using filesystem markdown files.

Directory structure follows the 3+1 layered model (System → Tenant → User → Session): 

{dataDir}/memory/{tenant_id}/users/{user_id}/sessions/{session_id}.md
{dataDir}/memory/{tenant_id}/users/{user_id}/sessions/{session_id}_summary.md

Thread safety is provided via per-file RWMutex stored in a sync.Map.

func NewMarkdownMemoryStore 

func NewMarkdownMemoryStore(dataDir string) (*MarkdownMemoryStore, error)

NewMarkdownMemoryStore creates a new markdown-backed conversation store.

func (*MarkdownMemoryStore) AppendMessage 

func (s *MarkdownMemoryStore) AppendMessage(ctx context.Context, msg agent.SessionMessage) error

AppendMessage adds a message to a session's conversation file.

func (*MarkdownMemoryStore) ClearSession 

func (s *MarkdownMemoryStore) ClearSession(ctx context.Context, tenantID, userID, sessionID string) error

ClearSession removes all messages and summary for a session.

func (*MarkdownMemoryStore) DataDir 

func (s *MarkdownMemoryStore) DataDir() string

DataDir returns the configured data directory path.

func (*MarkdownMemoryStore) GetHistory 

func (s *MarkdownMemoryStore) GetHistory(ctx context.Context, tenantID, userID, sessionID string, maxMessages int) ([]agent.Message, error)

GetHistory retrieves messages for a session in chronological order.

func (*MarkdownMemoryStore) GetSummary 

func (s *MarkdownMemoryStore) GetSummary(ctx context.Context, tenantID, userID, sessionID string) (string, error)

GetSummary retrieves the current summary for a session.

func (*MarkdownMemoryStore) StoreSummary 

func (s *MarkdownMemoryStore) StoreSummary(ctx context.Context, tenantID, userID, sessionID, summary string) error

StoreSummary persists a summary for a session.

type MemoryScope 

type MemoryScope struct {
	TenantID  string
	UserID    string
	SessionID string
}

MemoryScope contains tenant/user/session identifiers for memory operations.

type PgVectorStore 

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

PgVectorStore implements VectorStore using PostgreSQL + pgvector.

func NewPgVectorStore 

func NewPgVectorStore(pool *pgxpool.Pool, dimensions int) *PgVectorStore

NewPgVectorStore creates a new pgvector-backed vector store. The pool must be connected to a database with the pgvector extension enabled.

func (*PgVectorStore) Close 

func (s *PgVectorStore) Close() error

Close releases resources. Does NOT close the underlying pool — caller owns it.

func (*PgVectorStore) Delete 

func (s *PgVectorStore) Delete(ctx context.Context, filter DeleteFilter) error

Delete removes documents matching the filter.

func (*PgVectorStore) Migrate 

func (s *PgVectorStore) Migrate(ctx context.Context) error

Migrate creates the necessary tables and indexes.

func (*PgVectorStore) Search 

func (s *PgVectorStore) Search(ctx context.Context, query []float32, opts SearchOptions) ([]SearchResult, error)

Search returns the top-K most similar documents by cosine distance.

func (*PgVectorStore) Store 

func (s *PgVectorStore) Store(ctx context.Context, doc VectorDocument) error

Store saves a document with its embedding.

type RedisMemoryStore 

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

RedisMemoryStore implements ShortTermStore using Redis.

func NewRedisMemoryStore 

func NewRedisMemoryStore(client *redis.Client) *RedisMemoryStore

NewRedisMemoryStore creates a new Redis memory store.

func (*RedisMemoryStore) ClearSession 

func (s *RedisMemoryStore) ClearSession(ctx context.Context, sessionID string) error

ClearSession removes all entries for a session.

func (*RedisMemoryStore) Delete 

func (s *RedisMemoryStore) Delete(ctx context.Context, id string) error

Delete removes a memory entry.

func (*RedisMemoryStore) ListBySession 

func (s *RedisMemoryStore) ListBySession(ctx context.Context, sessionID string) ([]Entry, error)

ListBySession returns all entries for a session.

func (*RedisMemoryStore) Retrieve 

func (s *RedisMemoryStore) Retrieve(ctx context.Context, id string) (*Entry, error)

Retrieve gets a memory entry by ID.

func (*RedisMemoryStore) Store 

func (s *RedisMemoryStore) Store(ctx context.Context, entry Entry) error

Store saves a memory entry.

type SQLiteMemoryStore 

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

SQLiteMemoryStore implements ShortTermStore using SQLite.

func NewSQLiteMemoryStore 

func NewSQLiteMemoryStore(db *sql.DB) *SQLiteMemoryStore

NewSQLiteMemoryStore creates a new SQLite-backed memory store.

func (*SQLiteMemoryStore) ClearSession 

func (s *SQLiteMemoryStore) ClearSession(ctx context.Context, sessionID string) error

ClearSession removes all entries for a session.

func (*SQLiteMemoryStore) Delete 

func (s *SQLiteMemoryStore) Delete(ctx context.Context, id string) error

Delete removes a memory entry by ID, returning ErrNotFound if it doesn't exist.

func (*SQLiteMemoryStore) ListBySession 

func (s *SQLiteMemoryStore) ListBySession(ctx context.Context, sessionID string) ([]Entry, error)

ListBySession returns all non-expired entries for a session, ordered by created_at.

func (*SQLiteMemoryStore) Retrieve 

func (s *SQLiteMemoryStore) Retrieve(ctx context.Context, id string) (*Entry, error)

Retrieve gets a memory entry by ID, with lazy TTL expiry checking.

func (*SQLiteMemoryStore) Store 

func (s *SQLiteMemoryStore) Store(ctx context.Context, entry Entry) error

Store saves a memory entry, replacing any existing entry with the same ID.

type SearchOptions 

type SearchOptions struct {
	TenantID  string // required: tenant scope
	UserID    string // optional: restrict to user (empty = all users)
	SessionID string // optional: restrict to session (empty = all sessions)
	Limit     int    // max results (default: 10)
}

SearchOptions controls vector search behavior.

type SearchResult 

type SearchResult struct {
	VectorDocument
	Score float32 // cosine similarity (1.0 = identical)
}

SearchResult is a vector document with a similarity score.

type ShortTermStore 

type ShortTermStore interface {
	Store(ctx context.Context, entry Entry) error
	Retrieve(ctx context.Context, id string) (*Entry, error)
	ListBySession(ctx context.Context, sessionID string) ([]Entry, error)
	Delete(ctx context.Context, id string) error
	ClearSession(ctx context.Context, sessionID string) error
}

ShortTermStore provides short-term memory operations.

type SummarizingConversationStore 

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

SummarizingConversationStore wraps a ConversationStore and triggers summarization after each message append when the threshold is reached.

func NewSummarizingConversationStore 

func NewSummarizingConversationStore(inner agent.ConversationStore, summarizer *ConversationSummarizer) *SummarizingConversationStore

NewSummarizingConversationStore creates a decorator that auto-summarizes conversations.

func (*SummarizingConversationStore) AppendMessage 

func (s *SummarizingConversationStore) AppendMessage(ctx context.Context, msg agent.SessionMessage) error

func (*SummarizingConversationStore) ClearSession 

func (s *SummarizingConversationStore) ClearSession(ctx context.Context, tenantID, userID, sessionID string) error

func (*SummarizingConversationStore) GetHistory 

func (s *SummarizingConversationStore) GetHistory(ctx context.Context, tenantID, userID, sessionID string, maxMessages int) ([]agent.Message, error)

func (*SummarizingConversationStore) GetSummary 

func (s *SummarizingConversationStore) GetSummary(ctx context.Context, tenantID, userID, sessionID string) (string, error)

func (*SummarizingConversationStore) StoreSummary 

func (s *SummarizingConversationStore) StoreSummary(ctx context.Context, tenantID, userID, sessionID, summary string) error

type VectorDocument 

type VectorDocument struct {
	ID        string
	Content   string
	Embedding []float32
	TenantID  string
	UserID    string
	SessionID string
	Role      string
	CreatedAt time.Time
}

VectorDocument represents a document stored in the vector database.

type VectorStore 

type VectorStore interface {
	// Store saves a document with its embedding.
	Store(ctx context.Context, doc VectorDocument) error

	// Search returns the top-K most similar documents by cosine distance.
	Search(ctx context.Context, query []float32, opts SearchOptions) ([]SearchResult, error)

	// Delete removes documents matching the filter.
	Delete(ctx context.Context, filter DeleteFilter) error

	// Close releases resources.
	Close() error
}

VectorStore provides vector storage and similarity search. Implementations: pgvector (production), future: sqlite-vec, milvus.

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.