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

store

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Oct 12, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// HalfLifeDays controls how fast effective_importance decays.
	// After this many days without access, importance halves.
	HalfLifeDays = 30.0

	// MaxInsights is the default cap before auto-pruning kicks in for local SQLite.
	MaxInsights = 1000
	// ServerDefaultMaxInsights is the Helm/server default personal cap per principal.
	ServerDefaultMaxInsights = 25000

	// PruneBatchSize is how many excess insights to prune at once.
	PruneBatchSize = 10
)

Lifecycle constants

View Source 
const DefaultStoreName = "default"

DefaultStoreName is the fallback store when none is specified.

View Source 
const MaxOplogEntries = 5000

MaxOplogEntries is the maximum number of oplog entries to retain.

Variables

This section is empty.

Functions

func ActiveFile 

func ActiveFile(baseDir string) string

ActiveFile returns the path to <baseDir>/active.

func ComputeEffectiveImportance 

func ComputeEffectiveImportance(importance int, accessCount int, daysSinceAccess float64, edgeCount int) float64

ComputeEffectiveImportance calculates the current effective importance. Formula: base_weight(imp) * log(1 + access_count) * 0.5^(days_since_access / half_life) * (1 + 0.1*min(edges,5)) For newly created insights (0 days, 0 access), the access factor is log(1+0)=0, so we use max(1.0, log(1+access)) to ensure a non-zero baseline.

func DefaultDataDir 

func DefaultDataDir() string

DefaultDataDir returns ~/.mnemon.

func IsImmune 

func IsImmune(importance int, accessCount int) bool

IsImmune returns true if an insight should never be auto-pruned. Immune if: importance >= 4 OR access_count >= 3.

func ListStores 

func ListStores(baseDir string) ([]string, error)

ListStores returns sorted names of all stores under <baseDir>/data/.

func MaxInsightsFromEnv 

func MaxInsightsFromEnv(fallback int) int

MaxInsightsFromEnv returns MNEMON_MAX_INSIGHTS or fallback when unset/invalid.

func MigrateIfNeeded 

func MigrateIfNeeded(baseDir string) error

MigrateIfNeeded moves a legacy ~/.mnemon/mnemon.db into the new data/default/ layout. It is safe to call multiple times.

func ReadActive 

func ReadActive(baseDir string) string

ReadActive reads the active store name from <baseDir>/active. Returns DefaultStoreName if the file doesn't exist or is empty.

func StoreDir 

func StoreDir(baseDir, name string) string

StoreDir returns <baseDir>/data/<name>.

func StoreExists 

func StoreExists(baseDir, name string) bool

StoreExists checks whether the named store directory exists.

func ValidStoreName 

func ValidStoreName(name string) bool

ValidStoreName returns true if name matches [a-zA-Z0-9][a-zA-Z0-9_-]*.

func WriteActive 

func WriteActive(baseDir, name string) error

WriteActive writes the active store name to <baseDir>/active.

Types

type DB 

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

DB wraps a SQLite or Postgres database connection.

func Open 

func Open(dataDir string) (*DB, error)

Open opens (or creates) the SQLite database at the given directory.

func OpenReadOnly 

func OpenReadOnly(dataDir string) (*DB, error)

OpenReadOnly opens the SQLite database in read-only mode. Safe for read-only filesystem mounts: uses journal_mode=OFF to avoid writing WAL/SHM sidecar files.

func OpenWithOptions 

func OpenWithOptions(opts Options) (*DB, error)

OpenWithOptions opens SQLite (default) or Postgres from a connection URL.

func (*DB) AutoPrune 

func (db *DB) AutoPrune(maxInsights int, excludeIDs []string) (int, error)

AutoPrune soft-deletes the lowest effective_importance non-immune insights when total active count exceeds maxInsights. excludeIDs are protected from pruning (typically the just-created insights). Returns number pruned. If already inside a transaction (db.tx != nil), executes inline; otherwise wraps in its own transaction.

func (*DB) AutoPruneOwned 

func (db *DB) AutoPruneOwned(owner string, maxInsights int, excludeIDs []string) (int, error)

AutoPruneOwned soft-deletes personal-layer insights for owner when owner is set.

func (*DB) BoostRetention 

func (db *DB) BoostRetention(id string) error

BoostRetention boosts an insight's retention: access_count +3, refreshes last_accessed_at.

func (*DB) Close 

func (db *DB) Close() error

Close closes the database connection.

func (*DB) Conn 

func (db *DB) Conn() *sql.DB

Conn returns the underlying sql.DB for advanced queries.

func (*DB) DeleteEdge 

func (db *DB) DeleteEdge(sourceID string, targetID string, edgeType model.EdgeType) error

DeleteEdge removes one typed edge between two nodes.

func (*DB) DeleteEdgesByNode 

func (db *DB) DeleteEdgesByNode(nodeID string) error

DeleteEdgesByNode removes all edges referencing a node.

func (*DB) Dialect 

func (db *DB) Dialect() Dialect

Dialect returns the SQL dialect of this connection.

func (*DB) DisplayPath 

func (db *DB) DisplayPath() string

DisplayPath is safe to show to clients. Postgres DSNs have the password redacted.

func (*DB) EmbeddingStats 

func (db *DB) EmbeddingStats() (total int, embedded int, err error)

EmbeddingStats returns total insights and how many have embeddings.

func (*DB) FindInsightsWithEntity 

func (db *DB) FindInsightsWithEntity(entity string, excludeID string, limit int) ([]string, error)

FindInsightsWithEntity returns insight IDs that have the given entity in their entities JSON array.

func (*DB) GetActiveInsightsBySourceOrdered 

func (db *DB) GetActiveInsightsBySourceOrdered(source string) ([]*model.Insight, error)

GetActiveInsightsBySourceOrdered returns active insights for a source in chronological order.

func (*DB) GetActiveInsightsForDiff 

func (db *DB) GetActiveInsightsForDiff(owner, layer string) ([]*model.Insight, error)

GetActiveInsightsForDiff returns insights considered for duplicate/conflict detection. When owner is set, only that principal's personal-layer memories are returned.

func (*DB) GetAllActiveInsights 

func (db *DB) GetAllActiveInsights() ([]*model.Insight, error)

GetAllActiveInsights returns all non-deleted insights.

func (*DB) GetAllEdges 

func (db *DB) GetAllEdges() ([]*model.Edge, error)

GetAllEdges returns all edges in the graph.

func (*DB) GetAllEmbeddings 

func (db *DB) GetAllEmbeddings() ([]EmbeddedInsight, error)

GetAllEmbeddings returns all active insights that have embeddings.

func (*DB) GetEdgesByNode 

func (db *DB) GetEdgesByNode(nodeID string) ([]*model.Edge, error)

GetEdgesByNode returns all edges where the given node is source or target. Uses UNION ALL to allow SQLite to use separate indexes on source_id and target_id.

func (*DB) GetEdgesByNodeAndType 

func (db *DB) GetEdgesByNodeAndType(nodeID string, edgeType model.EdgeType) ([]*model.Edge, error)

GetEdgesByNodeAndType returns edges for a node filtered by edge type. Uses UNION ALL to allow SQLite to use composite indexes.

func (*DB) GetEdgesBySourceAndType 

func (db *DB) GetEdgesBySourceAndType(sourceID string, edgeType model.EdgeType) ([]*model.Edge, error)

GetEdgesBySourceAndType returns edges where the given node is source, filtered by type.

func (*DB) GetEmbedding 

func (db *DB) GetEmbedding(id string) ([]byte, error)

GetEmbedding returns the raw embedding blob for an insight.

func (*DB) GetInsightByID 

func (db *DB) GetInsightByID(id string) (*model.Insight, error)

GetInsightByID returns a single insight by ID (excludes soft-deleted).

func (*DB) GetInsightByIDIncludeDeleted 

func (db *DB) GetInsightByIDIncludeDeleted(id string) (*model.Insight, error)

GetInsightByIDIncludeDeleted returns a single insight by ID, including soft-deleted.

func (*DB) GetInsightsWithoutEmbedding 

func (db *DB) GetInsightsWithoutEmbedding(limit int) ([]*model.Insight, error)

GetInsightsWithoutEmbedding returns active insights that lack embeddings.

func (*DB) GetLatestInsightBySource 

func (db *DB) GetLatestInsightBySource(source string, excludeID string) (*model.Insight, error)

GetLatestInsightBySource returns the most recent non-deleted insight for a given source, excluding the given ID.

func (*DB) GetOplog 

func (db *DB) GetOplog(limit int) ([]OplogEntry, error)

GetOplog returns the most recent N oplog entries.

func (*DB) GetPrincipal 

func (db *DB) GetPrincipal(principal string) (*Principal, error)

GetPrincipal loads a principal row.

func (*DB) GetRecentInsightsBySource 

func (db *DB) GetRecentInsightsBySource(source string, excludeID string, limit int) ([]*model.Insight, error)

GetRecentInsightsBySource returns the N most recent non-deleted insights for a source, excluding the given ID.

func (*DB) GetRecentInsightsInWindow 

func (db *DB) GetRecentInsightsInWindow(excludeID string, windowHours float64, limit int) ([]*model.Insight, error)

GetRecentInsightsInWindow returns non-deleted insights created within the given time window (hours), excluding the given ID. Ordered by created_at DESC.

func (*DB) GetRetentionCandidates 

func (db *DB) GetRetentionCandidates(threshold float64, limit int) ([]RetentionCandidate, int, error)

GetRetentionCandidates returns non-immune insights sorted by effective_importance ascending. Uses bulk queries for last_accessed_at and edge counts instead of per-insight queries.

func (*DB) GetRetentionCandidatesOwned 

func (db *DB) GetRetentionCandidatesOwned(threshold float64, limit int, owner string) ([]RetentionCandidate, int, error)

GetRetentionCandidatesOwned lists GC candidates. When owner is set, only that principal's personal-layer memories are considered.

func (*DB) GetStats 

func (db *DB) GetStats() (*InsightStats, error)

GetStats returns aggregate statistics.

func (*DB) InTransaction 

func (db *DB) InTransaction(fn func(*DB) error) error

InTransaction runs fn inside a single SQL transaction. fn receives a scoped *DB whose tx pointer is private to this call, so concurrent InTransaction calls on the same *DB do not share db.tx. Store methods used inside fn must go through the scoped *DB, not the receiver.

func (*DB) IncrementAccessCount 

func (db *DB) IncrementAccessCount(id string) error

IncrementAccessCount bumps the access count and refreshes last_accessed_at. No-op when the database is read-only.

func (*DB) InsertEdge 

func (db *DB) InsertEdge(e *model.Edge) error

InsertEdge inserts or replaces an edge.

func (*DB) InsertInsight 

func (db *DB) InsertInsight(i *model.Insight) error

InsertInsight inserts a new insight into the database.

func (*DB) InsertIssuedToken 

func (db *DB) InsertIssuedToken(jti, principal string, expiresAt time.Time) error

InsertIssuedToken records a newly issued JWT id.

func (*DB) IsReadOnly 

func (db *DB) IsReadOnly() bool

IsReadOnly returns true if the database was opened in read-only mode.

func (*DB) LoadKnownEntities 

func (db *DB) LoadKnownEntities() (map[string]bool, error)

LoadKnownEntities returns the set of distinct entities that appear on at least one active (non-deleted) insight. It returns an empty (non-nil) map when no insights carry entities. The result is intended for use as a read-only filter — for example, by an index-aware entity extractor that admits wide-cast candidates only when they match a previously stored entity.

func (*DB) LogOp 

func (db *DB) LogOp(operation, insightID, detail string)

LogOp records an operation to the oplog and trims old entries beyond MaxOplogEntries. Best-effort: failures are logged to stderr but do not propagate. No-op when the database is read-only.

func (*DB) LookupIssuedToken 

func (db *DB) LookupIssuedToken(jti string) (*IssuedToken, error)

LookupIssuedToken returns a token row by jti.

func (*DB) Path 

func (db *DB) Path() string

Path returns the database file path.

func (*DB) Ping 

func (db *DB) Ping() error

Ping verifies the database is reachable.

func (*DB) QueryInsights 

func (db *DB) QueryInsights(f QueryFilter) ([]*model.Insight, error)

QueryInsights returns insights matching the filter, ordered by importance DESC, created_at DESC.

func (*DB) RefreshEffectiveImportance 

func (db *DB) RefreshEffectiveImportance(id string) (float64, error)

RefreshEffectiveImportance recomputes and stores effective_importance for one insight.

func (*DB) RevokeIssuedToken 

func (db *DB) RevokeIssuedToken(jti string) error

RevokeIssuedToken flags a jti as revoked.

func (*DB) RevokePrincipalTokens 

func (db *DB) RevokePrincipalTokens(principal string) error

RevokePrincipalTokens revokes every token for a principal.

func (*DB) ScanEmbeddings 

func (db *DB) ScanEmbeddings(fn func(id string, blob []byte) bool) error

ScanEmbeddings streams embeddings one at a time via callback, avoiding full-slice allocation. The callback returns true to continue scanning, false to stop early.

func (*DB) SetPrincipalDisabled 

func (db *DB) SetPrincipalDisabled(principal string, disabled bool) error

SetPrincipalDisabled toggles a principal without deleting history.

func (*DB) SoftDeleteInsight 

func (db *DB) SoftDeleteInsight(id string) error

SoftDeleteInsight sets deleted_at on an insight and removes all associated edges.

func (*DB) UpdateEmbedding 

func (db *DB) UpdateEmbedding(id string, blob []byte) error

UpdateEmbedding stores an embedding vector for an insight.

func (*DB) UpdateEntities 

func (db *DB) UpdateEntities(id string, entities []string) error

UpdateEntities updates the entities field for an insight.

func (*DB) UpsertPrincipal 

func (db *DB) UpsertPrincipal(principal, role string) error

UpsertPrincipal creates or updates a principal. Existing role is replaced.

type Dialect 

type Dialect int

Dialect is the SQL dialect used by a store connection. 

const (
	DialectSQLite Dialect = iota
	DialectPostgres
)

func (Dialect) String 

func (d Dialect) String() string

type EmbeddedInsight 

type EmbeddedInsight struct {
	ID        string
	Content   string
	Embedding []byte
}

EmbeddedInsight pairs an insight ID, content, and its embedding blob.

type EntityStat 

type EntityStat struct {
	Entity string `json:"entity"`
	Count  int    `json:"count"`
}

EntityStat holds entity link count info.

type InsightStats 

type InsightStats struct {
	Total        int            `json:"total"`
	ByCategory   map[string]int `json:"by_category"`
	EdgeCount    int            `json:"edge_count"`
	DeletedCount int            `json:"deleted_count"`
	TopEntities  []EntityStat   `json:"top_entities"`
	OplogCount   int            `json:"oplog_count"`
}

InsightStats holds aggregate statistics.

type IssuedToken 

type IssuedToken struct {
	JTI       string
	Principal string
	ExpiresAt time.Time
	Revoked   bool
	CreatedAt time.Time
}

IssuedToken is a revocable JWT identifier.

type OplogEntry 

type OplogEntry struct {
	ID        int    `json:"id"`
	Operation string `json:"operation"`
	InsightID string `json:"insight_id,omitempty"`
	Detail    string `json:"detail,omitempty"`
	CreatedAt string `json:"created_at"`
}

OplogEntry represents a single operation log entry.

type Options 

type Options struct {
	DataDir     string
	DatabaseURL string
	ReadOnly    bool
}

Options controls how a store is opened.

type OrgDocument 

type OrgDocument struct {
	ExternalRef string
	SourceURI   string
	Content     string
	Category    string
	Importance  int
	Tags        []string
	Entities    []string
}

OrgDocument is one organizational ground-truth record from an external source. Future wiki/plugin adapters implement OrgSource and upsert by ExternalRef.

type OrgSource 

type OrgSource interface {
	List(ctx context.Context) ([]OrgDocument, error)
}

OrgSource is a future plugin hook for organizational memories stored outside Postgres (for example a company wiki). Mnemon would list documents, upsert them as layer=org insights keyed by ExternalRef, then recall and adjust them like any other memory. Not implemented in this cut.

type Principal 

type Principal struct {
	Principal string
	Role      string
	Disabled  bool
	CreatedAt time.Time
}

Principal is a durable identity stored alongside memory data.

type QueryFilter 

type QueryFilter struct {
	Keyword       string
	Category      string
	MinImportance int
	Source        string
	Limit         int
}

QueryFilter holds optional filters for querying insights.

type RetentionCandidate 

type RetentionCandidate struct {
	Insight             *model.Insight `json:"insight"`
	EffectiveImportance float64        `json:"effective_importance"`
	DaysSinceAccess     float64        `json:"days_since_access"`
	EdgeCount           int            `json:"edge_count"`
	Immune              bool           `json:"immune"`
}

RetentionCandidate holds an insight and its effective importance breakdown.

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.