semanticmemory

package
v0.0.231 Latest Latest
Warning

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

 Go to latest Published: Aug 18, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package semanticmemory provides a local, inspectable durable-memory store for Comanda workflows. It intentionally uses SQLite FTS5 as its first retrieval engine so memory remains local, portable, and easy to debug.

Index

Constants

View Source 
const (
	GraphNodeComponent = "component"
	GraphNodePackage   = "package"
	GraphNodeFile      = "file"
	GraphNodeType      = "type"
	GraphNodeFunction  = "function"
	GraphNodeConcept   = "concept"
)

Graph node kinds.

View Source 
const (
	GraphEdgeContains  = "contains"
	GraphEdgeBelongsTo = "belongs_to"
	GraphEdgeImports   = "imports"
	GraphEdgeDefines   = "defines"
	GraphEdgeUses      = "uses"
	GraphEdgeReference = "references"
)

Graph edge kinds.

View Source 
const (
	GraphConfidenceExtracted = "extracted"
	GraphConfidenceInferred  = "inferred"
)

Graph edge confidence tags: extracted edges are explicit in the source, inferred edges come from name resolution or an LLM pass.

Variables

This section is empty.

Functions

func DefaultPath 

func DefaultPath(root, namespace string) string

DefaultPath returns the project-local database path for a namespace.

Types

type GraphAnnotation added in v0.0.227 

type GraphAnnotation struct {
	ID        string    `json:"id"`
	Namespace string    `json:"namespace"`
	NodeID    string    `json:"node_id"`
	Content   string    `json:"content"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

GraphAnnotation is durable, human-authored guidance attached to a graph node. It intentionally survives graph rebuilds so a fresh scan never discards a maintainer's direction to agents.

type GraphEdge added in v0.0.203 

type GraphEdge struct {
	ID         string
	Namespace  string
	SourceID   string
	TargetID   string
	Kind       string
	Confidence string
	Evidence   string
	CreatedAt  time.Time
	UpdatedAt  time.Time
}

GraphEdge is one typed, confidence-tagged connection between two nodes.

type GraphNode added in v0.0.203 

type GraphNode struct {
	ID        string
	Namespace string
	Kind      string
	Name      string
	Path      string
	Package   string
	Summary   string
	Degree    int
	CreatedAt time.Time
	UpdatedAt time.Time
}

GraphNode is one vertex in a knowledge graph stored alongside durable memory.

type GraphWriteProgress added in v0.0.217 

type GraphWriteProgress struct {
	Phase     string
	Current   string
	Completed int
	Total     int
}

GraphWriteProgress reports bounded milestones from a bulk graph replace. It intentionally does not expose a database transaction to callers.

type Record 

type Record struct {
	ID          string
	Namespace   string
	Type        string
	Priority    int
	Confidence  float64
	Content     string
	SourceRunID string
	SourceStep  string
	SourceRef   string
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

Record is one durable, independently understandable fact. Source fields preserve a route back to the workflow run or artifact that established it.

type SearchOptions 

type SearchOptions struct {
	Namespace string
	Types     []string
	Limit     int
}

SearchOptions bounds and filters a memory lookup.

type Store 

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

Store owns an SQLite database and its FTS index.

func Open 

func Open(path string) (*Store, error)

Open creates or opens a durable memory store at path.

func (*Store) Close 

func (s *Store) Close() error

Close releases the database connection.

func (*Store) DeleteGraphNamespace added in v0.0.203 

func (s *Store) DeleteGraphNamespace(ctx context.Context, namespace string) error

DeleteGraphNamespace removes all nodes, edges, and mirrored memory records for a namespace.

func (*Store) Get 

func (s *Store) Get(ctx context.Context, id string) (Record, error)

Get returns a memory by its durable ID.

func (*Store) GetGraphNode added in v0.0.203 

func (s *Store) GetGraphNode(ctx context.Context, id string) (GraphNode, error)

GetGraphNode returns a graph node by ID.

func (*Store) GraphAnnotations added in v0.0.227 

func (s *Store) GraphAnnotations(ctx context.Context, namespace, nodeID string) ([]GraphAnnotation, error)

GraphAnnotations lists durable human guidance for one graph node.

func (*Store) GraphEdges added in v0.0.203 

func (s *Store) GraphEdges(ctx context.Context, namespace string) ([]GraphEdge, error)

GraphEdges returns all edges in a namespace.

func (*Store) GraphFindNodes added in v0.0.203 

func (s *Store) GraphFindNodes(ctx context.Context, namespace, query string, limit int) ([]GraphNode, error)

GraphFindNodes looks nodes up by name/summary with FTS5, degrading to a LIKE search when the query cannot be expressed as FTS syntax.

func (*Store) GraphNeighborPage added in v0.0.220 

func (s *Store) GraphNeighborPage(ctx context.Context, namespace, nodeID string, limit, offset int) ([]GraphEdge, []GraphNode, bool, error)

GraphNeighborPage returns one stable, bounded page of a node's direct relationships. Browsers use it for progressive exploration of large graphs. Offset pagination keeps the API simple while the client caches loaded pages.

func (*Store) GraphNeighbors added in v0.0.203 

func (s *Store) GraphNeighbors(ctx context.Context, namespace, nodeID string) ([]GraphEdge, []GraphNode, error)

GraphNeighbors returns the edges touching a node (in either direction) and the nodes at the other end of those edges.

func (*Store) GraphNodeKindCounts added in v0.0.220 

func (s *Store) GraphNodeKindCounts(ctx context.Context, namespace string) (map[string]int, error)

GraphNodeKindCounts returns the number of nodes in each kind without materializing the graph.

func (*Store) GraphNodes added in v0.0.203 

func (s *Store) GraphNodes(ctx context.Context, namespace string) ([]GraphNode, error)

GraphNodes returns all nodes in a namespace.

func (*Store) GraphNodesByKind added in v0.0.220 

func (s *Store) GraphNodesByKind(ctx context.Context, namespace, kind string, limit int) ([]GraphNode, error)

GraphNodesByKind returns a bounded, highest-degree-first architectural slice of a graph. It deliberately avoids loading every symbol for browser views.

func (*Store) RefreshGraphDegrees added in v0.0.203 

func (s *Store) RefreshGraphDegrees(ctx context.Context, namespace string) error

RefreshGraphDegrees recomputes the degree column for every node in a namespace from the current edge set. Call once after a batch of edge writes.

func (*Store) ReplaceGraph added in v0.0.217 

func (s *Store) ReplaceGraph(ctx context.Context, namespace string, nodes []GraphNode, edges []GraphEdge, progress func(GraphWriteProgress)) error

ReplaceGraph atomically replaces one namespace using a single SQLite transaction. Rebuilds previously committed once per node, once per mirrored memory record, and once per edge; large graphs therefore spent most of their time in transaction overhead rather than graph work.

func (*Store) Search 

func (s *Store) Search(ctx context.Context, query string, options SearchOptions) ([]Record, error)

Search performs an FTS5 lookup. If a query cannot be expressed safely as FTS syntax, it degrades to a scoped LIKE search instead of failing a run.

func (*Store) Upsert 

func (s *Store) Upsert(ctx context.Context, record Record) (Record, error)

Upsert writes a fact and refreshes its FTS entry. Callers can pass a stable ID to update an existing fact; otherwise a new durable ID is generated.

func (*Store) UpsertGraphAnnotation added in v0.0.227 

func (s *Store) UpsertGraphAnnotation(ctx context.Context, annotation GraphAnnotation) (GraphAnnotation, error)

UpsertGraphAnnotation stores a human note and mirrors it as a graph_node memory record. Existing graph-aware semantic recall therefore includes the guidance without requiring each workflow to learn a separate annotation type.

func (*Store) UpsertGraphEdge added in v0.0.203 

func (s *Store) UpsertGraphEdge(ctx context.Context, edge GraphEdge) (GraphEdge, error)

UpsertGraphEdge writes a graph edge. Callers should pass a stable ID derived from (source, target, kind) so rebuilds update in place.

func (*Store) UpsertGraphNode added in v0.0.203 

func (s *Store) UpsertGraphNode(ctx context.Context, node GraphNode) (GraphNode, error)

UpsertGraphNode writes a graph node, refreshes its FTS entry, and mirrors it as a memory record (type graph_node) so memory search and workflow recall can find graph concepts. Callers should pass a stable ID so rebuilds update in place instead of duplicating.

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.