store

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Sep 19, 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.