Documentation
¶
Index ¶
- func CreateCausalEdges(db *store.DB, insight *model.Insight) (int, error)
- func CreateEntityEdges(db *store.DB, insight *model.Insight) (int, error)
- func CreateSemanticEdges(db *store.DB, insight *model.Insight, embedCache EmbedCache) (int, error)
- func CreateTemporalEdge(db *store.DB, insight *model.Insight) (int, error)
- func ExtractEntities(text string) []string
- func ExtractEntitiesIndexed(text string, knownEntities map[string]bool) []string
- func HasCausalSignal(text string) bool
- func ResolveEntities(content string, provided []string, mode EntityMode) []string
- func ResolveEntitiesIndexed(content string, provided []string, mode EntityMode, ...) []string
- func ValidEntityMode(mode EntityMode) bool
- type BFSNode
- type BFSOptions
- type CausalCandidate
- type EdgeStats
- type EmbedCache
- type Engine
- type EngineOptions
- type EntityMode
- type NeighborNode
- type SemanticCandidate
- type TemporalMode
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CreateCausalEdges ¶
CreateCausalEdges creates causal edges when either the new insight or a recent insight has causal signals and they share sufficient token overlap. Direction is inferred from which side has the causal keyword (MAGMA §3.3).
func CreateEntityEdges ¶
CreateEntityEdges creates entity co-occurrence edges between the new insight and existing insights that share the same entities.
func CreateSemanticEdges ¶
CreateSemanticEdges auto-creates semantic edges for insights with high embedding cosine similarity (MAGMA §3.2: cos(v_i, v_j) > θ_sim). If embedCache is non-nil, it is used instead of querying the database. Returns the number of edges created. Query and insert errors are returned so a surrounding SQL transaction can roll back.
func CreateTemporalEdge ¶
CreateTemporalEdge creates a backbone temporal edge between the new insight and the most recent insight from the same source (MAGMA backbone chain), plus proximity edges to recent insights within a 24h window.
func ExtractEntities ¶
ExtractEntities extracts named entities from text using regex patterns and a technology dictionary for common terms regex would miss.
func ExtractEntitiesIndexed ¶
ExtractEntitiesIndexed extends ExtractEntities with a fourth extraction path: a wide-cast regex over capitalized tokens plus a tokenized scan over the rest of the text, whose candidates are admitted only when they appear in knownEntities. The index is used purely as a filter (never as a generator), so this stays read-only with respect to the entity store and never feeds its own output back into the index.
The fourth path exists because the default regex+dictionary paths short-circuit to an empty entity set on text whose only entities are single-segment CamelCase names (e.g., personal-project vocabulary) that are not in techDictionary. When such names already appear on prior insights — i.e., live in the entity index — the indexed extractor admits them on subsequent text without any dictionary edit.
When knownEntities is nil or empty, behavior is identical to ExtractEntities. Callers without DB access can pass nil to get the pre-existing semantics.
func HasCausalSignal ¶
HasCausalSignal returns true if the text contains causal keywords.
func ResolveEntities ¶
func ResolveEntities(content string, provided []string, mode EntityMode) []string
ResolveEntities returns the final entity list for a content/provided pair.
func ResolveEntitiesIndexed ¶
func ResolveEntitiesIndexed(content string, provided []string, mode EntityMode, knownEntities map[string]bool) []string
ResolveEntitiesIndexed is the index-aware sibling of ResolveEntities. See ExtractEntitiesIndexed for the fourth-path semantics. A nil knownEntities map is identical to calling ResolveEntities.
func ValidEntityMode ¶
func ValidEntityMode(mode EntityMode) bool
ValidEntityMode reports whether mode is a supported entity handling mode.
Types ¶
type BFSOptions ¶
type BFSOptions struct {
MaxDepth int // maximum hop distance from start
MaxNodes int // maximum nodes to return (0 = unlimited)
EdgeFilter model.EdgeType // filter by edge type (empty = all types)
}
BFSOptions controls BFS traversal behavior.
type CausalCandidate ¶
type CausalCandidate struct {
ID string `json:"id"`
Content string `json:"content"`
Category string `json:"category"`
Hop int `json:"hop"` // graph distance (1 or 2)
ViaEdge string `json:"via_edge"` // edge type that connected
CausalSignal string `json:"causal_signal"` // keyword if found, else ""
SuggestedSubType string `json:"suggested_sub_type"` // heuristic suggestion
}
CausalCandidate represents a potential causal link for Claude to evaluate.
func FindCausalCandidates ¶
func FindCausalCandidates(db *store.DB, insight *model.Insight) []CausalCandidate
FindCausalCandidates returns insights that may have causal relationships with the given insight. Uses 2-hop BFS neighborhood traversal (MAGMA §3.3) to discover candidates through the existing graph structure, then annotates each with causal signal keywords as auxiliary labels for Claude to evaluate.
type EdgeStats ¶
type EdgeStats struct {
Temporal int `json:"temporal"`
Entity int `json:"entity"`
Causal int `json:"causal"`
Semantic int `json:"semantic"`
}
EdgeStats tracks how many edges of each type were created.
type EmbedCache ¶
EmbedCache maps insight ID → deserialized embedding vector. When passed as nil, functions fall back to loading from the database.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine orchestrates automatic edge creation when insights are stored.
func NewEngine ¶
func NewEngine(db *store.DB, embedCache EmbedCache) *Engine
NewEngine creates a new graph edge engine. If embedCache is non-nil, it is reused for semantic operations instead of querying the database.
func NewEngineWithEntityMode ¶
func NewEngineWithEntityMode(db *store.DB, embedCache EmbedCache, entityMode EntityMode) *Engine
NewEngineWithEntityMode creates a graph engine with configurable entity handling.
func NewEngineWithOptions ¶
func NewEngineWithOptions(db *store.DB, embedCache EmbedCache, options EngineOptions) *Engine
NewEngineWithOptions creates a graph engine with explicit generation options.
func (*Engine) OnInsightCreated ¶
OnInsightCreated runs all edge generators for a newly created insight. It merges any pre-provided entities (e.g. from LLM) with regex-extracted ones. Query and insert errors are returned so a surrounding SQL transaction can roll back.
type EngineOptions ¶
type EngineOptions struct {
EntityMode EntityMode
TemporalMode TemporalMode
}
EngineOptions configures automatic edge generation.
type EntityMode ¶
type EntityMode string
EntityMode controls how final insight entities are derived.
const ( // EntityModeMerge keeps pre-provided entities and supplements them with auto extraction. EntityModeMerge EntityMode = "merge" // EntityModeProvided uses only pre-provided entities. EntityModeProvided EntityMode = "provided" // EntityModeAuto uses only auto-extracted entities. EntityModeAuto EntityMode = "auto" )
type NeighborNode ¶
type NeighborNode struct {
ID string `json:"id"`
Content string `json:"content"`
Category string `json:"category"`
Hop int `json:"hop"` // 1 or 2
ViaEdge string `json:"via_edge"` // edge type that led here
}
NeighborNode represents a node discovered by BFS neighborhood traversal.
func GetNeighborhood ¶
GetNeighborhood performs a BFS from nodeID up to maxHops, following all edge types (temporal, semantic, causal, entity). Returns up to maxNodes neighbor nodes, excluding the start node and soft-deleted nodes.
type SemanticCandidate ¶
type SemanticCandidate struct {
ID string `json:"id"`
Content string `json:"content"`
Category string `json:"category"`
Similarity float64 `json:"similarity"`
AutoLinked bool `json:"auto_linked"`
}
SemanticCandidate represents a potential semantic link for Claude to evaluate. When AutoLinked is true, the edge was already created automatically (high confidence). When false, the candidate is in the review zone and needs LLM judgment.
func FindSemanticCandidates ¶
func FindSemanticCandidates(db *store.DB, insight *model.Insight, embedCache EmbedCache) []SemanticCandidate
FindSemanticCandidates returns insights that are potential semantic matches for the given insight. When embeddings are available, uses cosine similarity (MAGMA-compliant); falls back to token overlap otherwise. If embedCache is non-nil, it is used instead of querying the database. These are candidates only — Claude evaluates and creates actual semantic edges via `mnemon link`.
type TemporalMode ¶
type TemporalMode string
TemporalMode controls whether the engine creates temporal edges.
const ( // TemporalEnabled creates temporal edges using the normal real-time write path. TemporalEnabled TemporalMode = "enabled" // TemporalDisabled skips temporal edges. Import paths can repair historical // temporal edges after all backdated insights are written. TemporalDisabled TemporalMode = "disabled" )
Source Files