domain

Documentation

Index

• Constants
• func BetterSummary(a, b string) string
• func CombineWeights(a, b float64) float64
• func CombineWeightsMulti(weights []float64) float64
• type Community
• type DecayState
• type EmbedConfig
• type Entity
• type Episode
• type Feedback
  • func NewFeedback(kbID, topic, content, correction, source string) *Feedback
• type FeedbackStats
• type IngestionJob
• type KnowledgeBase
• type LLMConfig
• type MemoryStats
• type Relation
• type SearchResult
• type Subgraph
• type SubgraphEdge
• type SubgraphNode

Constants

const (
	ProviderOllama = "ollama"
	ProviderOpenAI = "openai"
	ProviderGenAI  = "genai"
	ProviderGemini = "gemini" // alias for genai
	ProviderVertex = "vertex"
	ProviderAzure  = "azure"
	ProviderGroq   = "groq"
)

Provider name constants used in EmbedConfig.Provider and LLMConfig.Provider.

const (
	DefaultEmbedModel = "nomic-embed-text"
	DefaultLLMModel   = "llama3.2"
)

Default model names used when creating knowledge bases without explicit config.

const (
	ItemEntity   = "entity"
	ItemRelation = "relation"
	ItemEpisode  = "episode"
)

Item type constants used in SearchResult.Type, DecayState.EntityType, and LogAccess.

const (
	JobStatusQueued    = "queued"
	JobStatusRunning   = "running"
	JobStatusCompleted = "completed"
	JobStatusFailed    = "failed"
)

Ingestion job statuses.

Functions

func BetterSummary

func BetterSummary(a, b string) string

BetterSummary returns the longer of two summaries. Used as a heuristic: a longer summary typically contains more information.

func CombineWeights

func CombineWeights(a, b float64) float64

CombineWeights merges two confidence weights using probability union. Result is bounded to [0, 1] and monotonically increasing with each observation. Examples: (0.5, 0.5) → 0.75, (0.8, 0.5) → 0.90, (1.0, x) → 1.0, (0, 0) → 0.

func CombineWeightsMulti

func CombineWeightsMulti(weights []float64) float64

CombineWeightsMulti merges multiple weights via repeated probability union.

Types

type Community

type Community struct {
	ID        string    `json:"id"`
	KBID      string    `json:"kb_id"`
	Name      string    `json:"name"`
	Summary   string    `json:"summary"`
	MemberIDs []string  `json:"member_ids"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

Community is a cluster summary over a group of entities.

type DecayState

type DecayState struct {
	EntityType  string    `json:"entity_type"` // "entity", "relation", "episode"
	EntityID    string    `json:"entity_id"`
	KBID        string    `json:"kb_id"`
	Strength    float64   `json:"strength"` // [0, 1]
	AccessCount int       `json:"access_count"`
	LastAccess  time.Time `json:"last_access"`
}

DecayState tracks memory strength for a single item.

type EmbedConfig

type EmbedConfig struct {
	Provider string `json:"provider"` // "ollama", "openai", "gemini"
	Model    string `json:"model"`    // "nomic-embed-text", "text-embedding-3-small"
	BaseURL  string `json:"base_url,omitempty"`
	APIKey   string `json:"-"`             // excluded from JSON output; stored separately
	Dim      int    `json:"dim,omitempty"` // embedding dimensions (0 = auto-detect)
}

EmbedConfig specifies which embedding provider and model to use.

type Entity

type Entity struct {
	ID        string    `json:"id"`
	KBID      string    `json:"kb_id"`
	Name      string    `json:"name"`
	Type      string    `json:"type"` // "person", "project", "concept", etc.
	Summary   string    `json:"summary"`
	Embedding []float32 `json:"-"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

Entity is an extracted node in the knowledge graph.

type Episode

type Episode struct {
	ID        string            `json:"id"`
	KBID      string            `json:"kb_id"`
	Content   string            `json:"content"`
	Source    string            `json:"source"` // "mcp", "api", "cli"
	Metadata  map[string]string `json:"metadata,omitempty"`
	CreatedAt time.Time         `json:"created_at"`
}

Episode represents a raw interaction stored verbatim.

type Feedback

type Feedback struct {
	ID         string            `json:"id"`
	KBID       string            `json:"kb_id"`
	Topic      string            `json:"topic"`
	Content    string            `json:"content"`              // what went wrong or what feedback is about
	Correction string            `json:"correction,omitempty"` // the correct answer or fix
	Source     string            `json:"source"`               // "mcp", "api", "cli"
	Metadata   map[string]string `json:"metadata,omitempty"`
	CreatedAt  time.Time         `json:"created_at"`
}

Feedback records a correction or feedback on a memory item for closed-loop learning.

func NewFeedback

func NewFeedback(kbID, topic, content, correction, source string) *Feedback

NewFeedback constructs a Feedback with a generated ID and current timestamp.

type FeedbackStats

type FeedbackStats struct {
	KBID        string         `json:"kb_id"`
	TotalCount  int            `json:"total_count"`
	TopicCounts map[string]int `json:"topic_counts"`
}

FeedbackStats holds aggregate feedback metrics for a KB.

type IngestionJob

type IngestionJob struct {
	ID          string            `json:"id"`
	KBID        string            `json:"kb_id"`
	Status      string            `json:"status"`
	Content     string            `json:"-"`
	Source      string            `json:"source"`
	Metadata    map[string]string `json:"metadata,omitempty"`
	EpisodeID   string            `json:"episode_id,omitempty"`
	Result      json.RawMessage   `json:"result,omitempty"`
	Error       string            `json:"error,omitempty"`
	Attempts    int               `json:"attempts"`
	MaxAttempts int               `json:"max_attempts"`
	CreatedAt   time.Time         `json:"created_at"`
	StartedAt   *time.Time        `json:"started_at,omitempty"`
	CompletedAt *time.Time        `json:"completed_at,omitempty"`
}

IngestionJob tracks an ingestion request through its lifecycle.

type KnowledgeBase

type KnowledgeBase struct {
	ID          string            `json:"id"`
	Name        string            `json:"name"`
	Description string            `json:"description,omitempty"`
	EmbedConfig EmbedConfig       `json:"embed_config"`
	LLMConfig   LLMConfig         `json:"llm_config"`
	Settings    map[string]string `json:"settings,omitempty"`
	CreatedAt   time.Time         `json:"created_at"`
}

KnowledgeBase defines an isolated memory space with its own LLM/embedding config.

type LLMConfig

type LLMConfig struct {
	Provider string `json:"provider"` // "ollama", "openai", "genai", "gemini", "vertex", "azure", "groq"
	Model    string `json:"model"`    // "llama3.2", "gemini-2.5-flash", "gpt-4o-mini"
	BaseURL  string `json:"base_url,omitempty"`
	APIKey   string `json:"-"` // excluded from JSON output; stored separately
}

LLMConfig specifies which LLM provider and model to use for extraction.

type MemoryStats

type MemoryStats struct {
	KBID             string    `json:"kb_id,omitempty"`
	TotalEpisodes    int       `json:"total_episodes"`
	TotalEntities    int       `json:"total_entities"`
	TotalRelations   int       `json:"total_relations"`
	TotalCommunities int       `json:"total_communities"`
	DBSizeBytes      int64     `json:"db_size_bytes"`
	LastIngestion    time.Time `json:"last_ingestion,omitempty"`
	LastDecayRun     time.Time `json:"last_decay_run,omitempty"`
}

MemoryStats holds system health metrics.

type Relation

type Relation struct {
	ID        string     `json:"id"`
	KBID      string     `json:"kb_id"`
	SourceID  string     `json:"source_id"`
	TargetID  string     `json:"target_id"`
	Type      string     `json:"type"` // "works_on", "knows", "uses", etc.
	Summary   string     `json:"summary"`
	Weight    float64    `json:"weight"`
	Embedding []float32  `json:"-"`
	EpisodeID string     `json:"episode_id,omitempty"` // provenance
	ValidAt   time.Time  `json:"valid_at"`             // when the fact became true
	InvalidAt *time.Time `json:"invalid_at,omitempty"` // nil = still valid
	CreatedAt time.Time  `json:"created_at"`           // transaction time
}

Relation is a bitemporal edge between two entities.

type SearchResult

type SearchResult struct {
	ID       string            `json:"id"`
	KBID     string            `json:"kb_id"`
	Type     string            `json:"type"` // "entity", "relation", "episode"
	Content  string            `json:"content"`
	Score    float64           `json:"score"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

SearchResult is a unified result from hybrid retrieval.

type Subgraph

type Subgraph struct {
	Nodes []SubgraphNode `json:"nodes"`
	Edges []SubgraphEdge `json:"edges"`
}

Subgraph is a structured ego-graph neighborhood with full node and edge metadata.

type SubgraphEdge

type SubgraphEdge struct {
	ID        string     `json:"id"`
	SourceID  string     `json:"source_id"`
	TargetID  string     `json:"target_id"`
	Type      string     `json:"type"`
	Weight    float64    `json:"weight"`
	ValidAt   time.Time  `json:"valid_at"`
	InvalidAt *time.Time `json:"invalid_at,omitempty"`
}

SubgraphEdge is a relation within a retrieved subgraph, including temporal data.

type SubgraphNode

type SubgraphNode struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Type     string `json:"type"`
	Summary  string `json:"summary"`
	Distance int    `json:"distance"`
}

SubgraphNode is an entity within a retrieved subgraph, annotated with hop distance.