Documentation
¶
Overview ¶
Package knowledge provides long-term semantic memory — facts the agent learns through conversation and ingestion, stored with optional embeddings for natural-language recall.
Index ¶
- func CosineSimilarity(a, b []float32) float32
- func DecodeEmbedding(data []byte) []float32
- func EncodeEmbedding(embedding []float32) []byte
- func SubjectsFromContext(ctx context.Context) []string
- func TopK(query []float32, vectors [][]float32, k int) []int
- func WithSubjects(ctx context.Context, subjects []string) context.Context
- type Category
- type Chunk
- type Client
- type Config
- type ContextProvider
- type EmbeddingClient
- type Fact
- type ForgetArgs
- type MarkdownIngester
- type RecallArgs
- type RememberArgs
- type SemanticRecallArgs
- type Store
- func (s *Store) Close() error
- func (s *Store) Delete(category Category, key string) error
- func (s *Store) DeleteBySource(source string) error
- func (s *Store) Get(category Category, key string) (*Fact, error)
- func (s *Store) GetAll() ([]*Fact, error)
- func (s *Store) GetAllWithEmbeddings() ([]*Fact, error)
- func (s *Store) GetByCategory(category Category) ([]*Fact, error)
- func (s *Store) GetBySubjects(subjects []string) ([]*Fact, error)
- func (s *Store) GetFactsWithoutEmbeddings() ([]*Fact, error)
- func (s *Store) Search(query string) ([]*Fact, error)
- func (s *Store) SemanticSearch(queryEmbedding []float32, limit int) ([]*Fact, []float32, error)
- func (s *Store) Set(category Category, key, value, source string, confidence float64, ...) (*Fact, error)
- func (s *Store) SetEmbedding(id uuid.UUID, embedding []float32) error
- func (s *Store) Stats() map[string]any
- type SubjectContextProvider
- type Tools
- func (t *Tools) Forget(argsJSON string) (string, error)
- func (t *Tools) GenerateMissingEmbeddings() (int, error)
- func (t *Tools) GetDefinitions() []map[string]any
- func (t *Tools) Recall(argsJSON string) (string, error)
- func (t *Tools) Remember(argsJSON string) (string, error)
- func (t *Tools) SemanticRecall(argsJSON string) (string, error)
- func (t *Tools) SetEmbeddingClient(client EmbeddingClient)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CosineSimilarity ¶
CosineSimilarity computes cosine similarity between two vectors.
func DecodeEmbedding ¶
DecodeEmbedding converts bytes back to a float32 slice.
func EncodeEmbedding ¶
EncodeEmbedding converts a float32 slice to bytes for storage.
func SubjectsFromContext ¶
SubjectsFromContext extracts subject keys from the context. Returns nil if no subjects were set.
func WithSubjects ¶
WithSubjects adds subject keys to the context for pre-warming. Downstream context providers can retrieve these via SubjectsFromContext to query subject-keyed
Types ¶
type Category ¶
type Category string
Category groups related
const ( CategoryUser Category = "user" // User preferences and info CategoryHome Category = "home" // Home layout, room names CategoryDevice Category = "device" // Device mappings and traits CategoryRoutine Category = "routine" // Observed patterns CategoryPreference Category = "preference" // How the user likes things CategoryArchitecture Category = "architecture" // System design knowledge )
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client generates embeddings using Ollama's embedding API.
type Config ¶
type Config struct {
BaseURL string // Ollama base URL (e.g., "http://localhost:11434")
Model string // Embedding model (e.g., "nomic-embed-text")
}
Config for embedding client.
type ContextProvider ¶
type ContextProvider struct {
// contains filtered or unexported fields
}
ContextProvider provides relevant facts as context for the system prompt.
func NewContextProvider ¶
func NewContextProvider(store *Store, embedder *Client) *ContextProvider
NewContextProvider creates a context provider.
func (*ContextProvider) GetContext ¶
GetContext returns relevant facts formatted for the system prompt. Implements agent.ContextProvider interface.
func (*ContextProvider) SetMaxFacts ¶
func (p *ContextProvider) SetMaxFacts(n int)
SetMaxFacts configures how many facts to include.
func (*ContextProvider) SetMinScore ¶
func (p *ContextProvider) SetMinScore(score float32)
SetMinScore configures the minimum similarity threshold.
type EmbeddingClient ¶
EmbeddingClient generates embeddings for semantic search.
type Fact ¶
type Fact struct {
ID uuid.UUID `json:"id"`
Category Category `json:"category"`
Key string `json:"key"` // Unique within category
Value string `json:"value"` // The actual information
Source string `json:"source,omitempty"` // Where we learned this
Confidence float64 `json:"confidence,omitempty"` // 0-1, how certain
Subjects []string `json:"subjects,omitempty"` // Subject keys (e.g., "entity:foo", "zone:bar")
Ref string `json:"ref,omitempty"` // Knowledge base relative path (e.g., "dossiers/openclawssy.md")
Embedding []float32 `json:"embedding,omitempty"` // Vector embedding for semantic search
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
AccessedAt time.Time `json:"accessed_at"` // For LRU-style relevance
}
Fact represents a piece of long-term memory.
type ForgetArgs ¶
ForgetArgs are arguments for the forget_fact tool.
type MarkdownIngester ¶
type MarkdownIngester struct {
// contains filtered or unexported fields
}
MarkdownIngester parses markdown documents into
func NewMarkdownIngester ¶
func NewMarkdownIngester(store *Store, embeddings EmbeddingClient, source string, category Category) *MarkdownIngester
NewMarkdownIngester creates a markdown document ingester. Category determines how facts are categorized (e.g., CategoryArchitecture).
func (*MarkdownIngester) IngestFile ¶
IngestFile reads and processes a markdown file into
func (*MarkdownIngester) IngestString ¶
IngestString processes markdown content from a string.
type RecallArgs ¶
type RecallArgs struct {
Category string `json:"category,omitempty"` // Optional filter
Key string `json:"key,omitempty"` // Specific key to recall
Query string `json:"query,omitempty"` // Search term
}
RecallArgs are arguments for the recall_fact tool.
type RememberArgs ¶
type RememberArgs struct {
Category string `json:"category"` // user, home, device, routine, preference
Key string `json:"key"` // Unique identifier within category
Value string `json:"value"` // The information to remember
Source string `json:"source,omitempty"` // Where this came from
Subjects []string `json:"subjects,omitempty"` // Subject keys (e.g., "entity:foo", "zone:bar")
Ref string `json:"ref,omitempty"` // KB-relative path (e.g., "dossiers/openclawssy.md")
}
RememberArgs are arguments for the remember_fact tool.
type SemanticRecallArgs ¶
SemanticRecallArgs are arguments for semantic_recall tool.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store manages fact persistence.
func NewStoreWithDB ¶
NewStoreWithDB creates a fact store using an existing database connection.
func (*Store) DeleteBySource ¶
DeleteBySource soft-deletes all facts from a given source. Used for re-importing documents without duplicates.
func (*Store) GetAllWithEmbeddings ¶
GetAllWithEmbeddings returns all facts that have
func (*Store) GetByCategory ¶
GetByCategory retrieves all facts in a category.
func (*Store) GetBySubjects ¶
GetBySubjects retrieves all active facts associated with any of the given subject keys. Subjects are stored as JSON arrays and queried using SQLite's json_each() function. Returns nil when no subjects are provided or no facts match.
func (*Store) GetFactsWithoutEmbeddings ¶
GetFactsWithoutEmbeddings returns facts that need embeddings generated.
func (*Store) Search ¶
Search finds facts matching the query. Uses FTS5 full-text search when available, falling back to LIKE-based search otherwise.
func (*Store) SemanticSearch ¶
SemanticSearch finds facts similar to the query embedding.
func (*Store) Set ¶
func (s *Store) Set(category Category, key, value, source string, confidence float64, subjects []string, ref string) (*Fact, error)
Set creates or updates a fact. Resurrects soft-deleted facts if they exist. Subjects is an optional list of subject keys (e.g., "entity:foo", "zone:bar") stored as a JSON array. Pass nil to leave subjects unset. Ref is an optional knowledge-base-relative path (e.g., "dossiers/foo.md"). Pass "" to leave ref unset.
func (*Store) SetEmbedding ¶
SetEmbedding updates a fact's embedding vector.
type SubjectContextProvider ¶
type SubjectContextProvider struct {
// contains filtered or unexported fields
}
SubjectContextProvider injects facts keyed to specific subjects into the system prompt. Used for pre-warming cold-start loops with relevant context before the model sees the triggering event.
Subject keys are passed through the context via WithSubjects. When no subjects are present in the context, GetContext returns empty.
func NewSubjectContextProvider ¶
func NewSubjectContextProvider(store *Store, logger *slog.Logger) *SubjectContextProvider
NewSubjectContextProvider creates a subject context provider with default settings (maxFacts=10).
func (*SubjectContextProvider) GetContext ¶
GetContext returns subject-keyed facts formatted for the system prompt. Implements the agent.ContextProvider interface.
Subjects are extracted from the context via SubjectsFromContext. If no subjects are present, returns empty. The userMessage parameter is unused — subject matching is purely key-based, not semantic.
func (*SubjectContextProvider) SetMaxFacts ¶
func (p *SubjectContextProvider) SetMaxFacts(n int)
SetMaxFacts configures the maximum number of subject-matched facts to include in the context.
type Tools ¶
type Tools struct {
// contains filtered or unexported fields
}
Tools provides fact-related tools for the agent.
func (*Tools) GenerateMissingEmbeddings ¶
GenerateMissingEmbeddings creates embeddings for facts that don't have them. Returns count of facts embedded.
func (*Tools) GetDefinitions ¶
GetDefinitions returns tool definitions for the fact tools.
func (*Tools) SemanticRecall ¶
SemanticRecall finds facts semantically similar to the query.
func (*Tools) SetEmbeddingClient ¶
func (t *Tools) SetEmbeddingClient(client EmbeddingClient)
SetEmbeddingClient sets the embedding client for semantic search.
Source Files