Help us shape the future of Go! Take the 2026 Go Developer Survey

engine

package
v0.8.1 Latest Latest
Warning

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

 Go to latest Published: Oct 21, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package engine holds the Engine — the single orchestrator and entry point for the SDK / CLI / MCP. All front-ends call the same Engine so behaviour is identical everywhere.

Index

Constants

This section is empty.

Variables

View Source 
var ErrResourceRequired = errors.New("recall_operations: resource is required")

ErrResourceRequired is returned when a recall_ops query omits the mandatory resource slot (front-ends should validate first).

Functions

This section is empty.

Types

type Engine 

type Engine struct {
	Config   *config.Config
	Provider storage.EmbeddingProvider
	Store    storage.Store

	Working     *layers.WorkingMemory
	Episodic    *layers.EpisodicMemory
	Semantic    *layers.SemanticMemory
	Procedural  *layers.ProceduralMemory
	Associative *layers.AssociativeMemory
	// contains filtered or unexported fields
}

Engine is the top-level LadyM orchestrator.

func New 

func New(cfg *config.Config) (*Engine, error)

New builds an Engine from cfg (defaults to config.Default() when nil).

func NewWithModels 

func NewWithModels(cfg *config.Config, models *adapter.ModelRouting) (*Engine, error)

NewWithModels builds an Engine, optionally injecting host-owned models via routing (embedding provider + per-op LLM providers).

func (*Engine) AttachLLMClassifier 

func (e *Engine) AttachLLMClassifier(fn operations.LLMClassifier) error

AttachLLMClassifier wires an explicit consolidation classifier. When fn is nil it builds the consolidate agent from config (offline → heuristic).

func (*Engine) Close 

func (e *Engine) Close() error

Close releases the store.

func (*Engine) Consolidate 

func (e *Engine) Consolidate(workspace string, since float64) (*operations.ConsolidationReport, error)

Consolidate promotes episodic events into semantic facts.

func (*Engine) CountRecentEpisodes 

func (e *Engine) CountRecentEpisodes(workspace string) (int, error)

CountRecentEpisodes counts episodic events in workspace.

func (*Engine) Decay 

func (e *Engine) Decay(workspace string, dryRun bool, maxAgeS, activationFloor float64) (*operations.DecayReport, error)

Decay forgets low-activation episodic events.

func (*Engine) ExtractMentalModels 

func (e *Engine) ExtractMentalModels(workspace string) (*operations.L5ExtractionReport, error)

ExtractMentalModels runs L5 extraction (skipped when no LLM is configured).

func (*Engine) Forget 

func (e *Engine) Forget(memoryID string) error

Forget deletes a single memory by id.

func (*Engine) IndexCode 

func (e *Engine) IndexCode(root string, force bool, workspace string, languages []string) (*code.IndexReport, error)

IndexCode indexes a codebase into L2 semantic memory. 

func (e *Engine) Link(srcID, dstID, relation string, opts ...LinkOption) (*schema.Edge, error)

Link creates an associative edge, passing weight/metadata/valid_from/valid_to through to the associative layer (Python: link(src, dst, relation, **kw)).

func (*Engine) List added in v0.3.1 

func (e *Engine) List(workspace string, layer *schema.Layer, limit, offset int) ([]*schema.Memory, error)

List returns a workspace's memories newest-first, excluding retired items (expired predictions, superseded models). limit<=0 means 20; offset pages (negative offset is clamped to 0). Read-only: it never calls the LLM.

func (*Engine) MaintainL4 added in v0.7.0 

func (e *Engine) MaintainL4(workspace string) (*operations.MaintainReport, error)

MaintainL4 runs the worker-maintenance step of a System 2 cycle: the store's dangling-edge GC plus the (gated) backfill / semantic-linking / alias-merge sub-steps. The three LLM agents are resolved per op; a missing agent means that sub-step runs in heuristic/offline mode.

func (*Engine) MinEpisodesToRun 

func (e *Engine) MinEpisodesToRun() int

MinEpisodesToRun returns the System 2 episode threshold.

func (*Engine) PredictForwardIntents 

func (e *Engine) PredictForwardIntents(workspace string) (*operations.L6PredictionReport, error)

PredictForwardIntents runs L6 prediction (skipped when no LLM is configured).

func (*Engine) Proceduralize 

func (e *Engine) Proceduralize(workspace string, minClusterSize int) (*operations.ProceduralizeReport, error)

Proceduralize clusters successful episodes into playbooks.

func (*Engine) Recall 

func (e *Engine) Recall(query string, workspace string, topK int, layers_ []schema.Layer, types []schema.MemoryType, minSimilarity float64) (*schema.RecallResponse, error)

Recall runs two-tier retrieval.

func (*Engine) RecallOperations added in v0.7.0 

func (e *Engine) RecallOperations(q OperationsQuery) (*OperationsResponse, error)

RecallOperations runs the recall_ops pivot query in the engine's default workspace; use Scope for a per-call workspace.

func (*Engine) RecordEvent 

func (e *Engine) RecordEvent(agent, action, observation, outcome string, tags []string, metadata map[string]any) (*schema.Memory, error)

RecordEvent logs an L1 episodic event in the engine's default workspace; use Scope for a per-call workspace.

func (*Engine) RecordOperation added in v0.7.0 

func (e *Engine) RecordOperation(ev OperationEvent) (*schema.Memory, error)

RecordOperation records an L1 operation with resource/action slots in the engine's default workspace; use Scope for a per-call workspace.

func (*Engine) Remember 

func (e *Engine) Remember(content string, layer schema.Layer, type_ schema.MemoryType, tags []string, metadata map[string]any, source, summary string) (*schema.Memory, error)

Remember is the generic write, routing to the right layer. It runs in the engine's default workspace; use Scope for a per-call workspace. It returns an unpersisted Memory tagged gated=dedropped when the attention gate drops the content.

func (*Engine) Scope added in v0.6.0 

func (e *Engine) Scope(workspace string) *Scope

Scope returns a view of the engine bound to workspace ("" = the engine's default workspace).

func (*Engine) SearchCode 

func (e *Engine) SearchCode(query string, topK int, workspace string) (*schema.RecallResponse, error)

SearchCode is a code-only shortcut.

func (*Engine) SetWorkspace 

func (e *Engine) SetWorkspace(ws string)

SetWorkspace retargets the engine's default workspace (used by the MCP tools which accept a per-call workspace override).

func (*Engine) StartSystem2 

func (e *Engine) StartSystem2(intervalS int, workspace string) chan struct{}

StartSystem2 launches a daemon goroutine running System2 cycles. Closing the returned channel asks the worker to stop after its current cycle.

func (*Engine) Stats 

func (e *Engine) Stats() (*schema.Stats, error)

Stats returns aggregate store statistics for the engine's default workspace.

func (*Engine) StatsFor added in v0.3.1 

func (e *Engine) StatsFor(workspace string) (*schema.Stats, error)

StatsFor returns aggregate store statistics scoped to the given workspace (empty string falls back to the engine's default workspace). Store-wide aggregates (edges, code symbols, workspace list) are not workspace-scoped.

func (*Engine) SweepDanglingEdges added in v0.7.0 

func (e *Engine) SweepDanglingEdges() (int, error)

SweepDanglingEdges delegates to the store's dangling-edge GC (System2 maintenance step).

type LinkOption 

type LinkOption func(*linkOpts)

LinkOption customises an associative edge created by Link.

func WithMetadata 

func WithMetadata(m map[string]any) LinkOption

WithMetadata sets the edge metadata.

func WithValidFrom 

func WithValidFrom(t float64) LinkOption

WithValidFrom sets the edge's valid-from timestamp.

func WithValidTo 

func WithValidTo(t float64) LinkOption

WithValidTo sets the edge's valid-to timestamp.

func WithWeight 

func WithWeight(w float64) LinkOption

WithWeight sets the edge weight. An explicit 0 is preserved (unlike the default, which is 1.0 when WithWeight is not given).

type OperationEvent added in v0.7.0 

type OperationEvent struct {
	Agent, Action, ActionClass string
	Resources                  []string
	Observation, Outcome       string
	Tags                       []string
	Metadata                   map[string]any
}

OperationEvent is a structured L1 write: explicit resource and action slots layered on the legacy record_event fields (spec §6.1). ActionClass, when empty, is derived from Action via the controlled vocabulary.

type OperationsQuery added in v0.7.0 

type OperationsQuery struct {
	Resource     string  // required: resource name or alias
	Action       string  // optional: action word (exact match after normalization)
	Since, Until float64 // optional: time window on episode creation time
	Outcome      string  // optional: "success" | "fail"
	Limit        int     // optional, default 10
}

OperationsQuery is the recall_ops pivot query: which operations touched this resource, optionally narrowed by action, time window, and outcome (spec §7.1).

type OperationsResponse added in v0.7.0 

type OperationsResponse struct {
	Resource *schema.Memory
	Items    []*schema.RecallResult
	Fallback bool
}

OperationsResponse is the recall_ops result: the resolved resource entity (nil on fallback), the matching episodes/facts as recall results, and the fallback marker for resource-miss degradation.

type Scope added in v0.6.0 

type Scope struct {
	Working    *layers.WorkingMemory
	Episodic   *layers.EpisodicMemory
	Semantic   *layers.SemanticMemory
	Procedural *layers.ProceduralMemory
	// contains filtered or unexported fields
}

Scope is a workspace-bound view of an Engine: it shares the engine's Store, Provider, Config, and lazily-built LLM agents, and holds layer handles bound to one workspace. Construction does no I/O, so concurrent front-ends (HTTP, langgraph nodes) can build one per request instead of mutating the shared engine's workspace fields.

func (*Scope) RecallOperations added in v0.7.0 

func (s *Scope) RecallOperations(q OperationsQuery) (*OperationsResponse, error)

RecallOperations runs the three-stage pivot pipeline (spec §7.2), with zero LLM on every branch: 

Stage 1 resource resolution: exact alias/content match, then vector
  nearest-neighbour with the read-side threshold (lower than the write
  side). A miss degrades to plain recall with Fallback=true.
Stage 2 graph connection: Neighbors(res, "operates_on") src side,
  filtered by workspace/retired/action_class/time window/outcome.
Stage 3 activation ranking: ACT-R ActivationScore with a flat sim proxy.

func (*Scope) RecordEvent added in v0.6.0 

func (s *Scope) RecordEvent(agent, action, observation, outcome string, tags []string, metadata map[string]any) (*schema.Memory, error)

RecordEvent logs an L1 episodic event. Legacy shape: no resource slots, no vocabulary stamping, no edges — byte-identical to the pre-operation write path; internally it delegates to the same pipeline with slots disabled.

func (*Scope) RecordOperation added in v0.7.0 

func (s *Scope) RecordOperation(ev OperationEvent) (*schema.Memory, error)

RecordOperation records an episodic event with structured slots: the action is normalized onto the vocabulary (ActionClass overrides), each resource is resolved to a workspace L2 resource entity, and an operates_on edge with a deterministic projected id links the episode to every resource.

func (*Scope) Remember added in v0.6.0 

func (s *Scope) Remember(content string, layer schema.Layer, type_ schema.MemoryType, tags []string, metadata map[string]any, source, summary string) (*schema.Memory, error)

Remember is the generic write, routing to the right layer. It returns an unpersisted Memory tagged gated=dedropped when the attention gate drops the content.

func (*Scope) Workspace added in v0.6.0 

func (s *Scope) Workspace() string

Workspace returns the scope's workspace.

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.