database

package
v1.2.2 Latest Latest
Warning

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

 Go to latest Published: Jan 27, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package database provides SQLite database layer with FTS5 full-text search.

This package implements the complete database schema with 16 verified tables, including memories, relationships, categories, domains, and supporting tables. It provides CRUD operations, search functionality, and graph traversal capabilities.

Index

Constants

View Source 
const CoreSchema = `` /* 11868-byte string literal not displayed */

CoreSchema contains the main table definitions VERIFIED: Exact schema from ~/.local-memory/unified-memories.db

View Source 
const FTS5Schema = `` /* 1495-byte string literal not displayed */

FTS5Schema contains the full-text search configuration VERIFIED: FTS5 virtual table with automatic sync triggers NOTE: Using standalone FTS5 table (not external content) for reliable trigger behavior

View Source 
const SchemaVersion = 1

SchemaVersion is the current schema version

Variables

View Source 
var AgentTypes = []string{
	"claude-desktop",
	"claude-code",
	"api",
	"unknown",
}

AgentTypes contains the 4 verified agent types

View Source 
var RelationshipTypes = []string{
	"references",
	"contradicts",
	"expands",
	"similar",
	"sequential",
	"causes",
	"enables",
}

RelationshipTypes contains the 7 verified relationship types

Functions

func IsValidAgentType 

func IsValidAgentType(t string) bool

IsValidAgentType checks if an agent type is valid

func IsValidRelationshipType 

func IsValidRelationshipType(t string) bool

IsValidRelationshipType checks if a relationship type is valid

func MigrationV1ToV2 

func MigrationV1ToV2(db *sql.DB) error

MigrationV1ToV2 migrates the database from schema version 1 to version 2 This adds temporal decay columns, entities tables, and updates FTS5

func ParseTags 

func ParseTags(s string) []string

ParseTags parses a JSON string into tags slice

Types

type AgentSession 

type AgentSession struct {
	SessionID    string    `json:"session_id"`
	AgentType    string    `json:"agent_type"` // One of 4 verified types
	AgentContext string    `json:"agent_context,omitempty"`
	CreatedAt    time.Time `json:"created_at"`
	LastAccessed time.Time `json:"last_accessed"`
	IsActive     bool      `json:"is_active"`
	Metadata     string    `json:"metadata"` // JSON string
}

AgentSession represents a session VERIFIED: Matches agent_sessions table schema

type AutonomousLoop 

type AutonomousLoop struct {
	ID          string     `json:"id"`
	StartedAt   time.Time  `json:"started_at"`
	CompletedAt *time.Time `json:"completed_at,omitempty"`
	Status      string     `json:"status"` // running, completed, stopped, failed

	// Configuration
	MaxIterations           int     `json:"max_iterations"`
	MinImprovementThreshold float64 `json:"min_improvement_threshold"`
	ConvergenceThreshold    float64 `json:"convergence_threshold"`

	// Results
	TotalIterations int      `json:"total_iterations"`
	BaselineScore   *float64 `json:"baseline_score,omitempty"`
	FinalScore      *float64 `json:"final_score,omitempty"`
	BestScore       *float64 `json:"best_score,omitempty"`
	BestRunID       string   `json:"best_run_id,omitempty"`

	// Stop reason
	StopReason string `json:"stop_reason,omitempty"`

	// Change tracking (JSON arrays)
	ChangesAttempted string `json:"changes_attempted,omitempty"`
	ChangesAccepted  string `json:"changes_accepted,omitempty"`
	ChangesRejected  string `json:"changes_rejected,omitempty"`
}

AutonomousLoop represents an autonomous improvement session

type BenchmarkCategoryResult 

type BenchmarkCategoryResult struct {
	ID       string `json:"id"`
	RunID    string `json:"run_id"`
	Category string `json:"category"` // single_hop, multi_hop, temporal, open_domain, adversarial

	// Scores
	LLMJudgeAccuracy *float64 `json:"llm_judge_accuracy,omitempty"`
	F1Score          *float64 `json:"f1_score,omitempty"`
	Bleu1Score       *float64 `json:"bleu1_score,omitempty"`

	// Counts
	TotalQuestions *int `json:"total_questions,omitempty"`
	CorrectCount   *int `json:"correct_count,omitempty"`

	// Comparison
	PreviousBestAccuracy *float64 `json:"previous_best_accuracy,omitempty"`
	Improvement          *float64 `json:"improvement,omitempty"`
}

BenchmarkCategoryResult represents per-category results

type BenchmarkQuestionResult 

type BenchmarkQuestionResult struct {
	ID    string `json:"id"`
	RunID string `json:"run_id"`

	// Question identification
	QuestionID   string `json:"question_id"`
	Category     string `json:"category"`
	QuestionText string `json:"question_text"`

	// Answers
	GoldAnswer      string `json:"gold_answer"`
	GeneratedAnswer string `json:"generated_answer,omitempty"`

	// Scores
	LLMJudgeLabel *int     `json:"llm_judge_label,omitempty"` // 0 or 1
	F1Score       *float64 `json:"f1_score,omitempty"`
	Bleu1Score    *float64 `json:"bleu1_score,omitempty"`

	// Context metrics
	ContextLength    *int `json:"context_length,omitempty"`
	MemoriesUsed     *int `json:"memories_used,omitempty"`
	RetrievalTimeMs  *int `json:"retrieval_time_ms,omitempty"`
	GenerationTimeMs *int `json:"generation_time_ms,omitempty"`

	// Comparison
	ChangedFromPrevious *bool `json:"changed_from_previous,omitempty"`
	PreviousWasCorrect  *bool `json:"previous_was_correct,omitempty"`
}

BenchmarkQuestionResult represents individual question results

type BenchmarkRun 

type BenchmarkRun struct {
	ID          string     `json:"id"`
	StartedAt   time.Time  `json:"started_at"`
	CompletedAt *time.Time `json:"completed_at,omitempty"`
	Status      string     `json:"status"` // pending, running, completed, failed, cancelled

	// Git context
	GitCommitHash string `json:"git_commit_hash"`
	GitBranch     string `json:"git_branch,omitempty"`
	GitDirty      bool   `json:"git_dirty"`

	// Configuration
	ConfigSnapshot string `json:"config_snapshot"` // JSON
	BenchmarkType  string `json:"benchmark_type"`  // locomo, etc.

	// Results
	OverallScore   *float64 `json:"overall_score,omitempty"`
	OverallF1      *float64 `json:"overall_f1,omitempty"`
	OverallBleu1   *float64 `json:"overall_bleu1,omitempty"`
	TotalQuestions *int     `json:"total_questions,omitempty"`
	TotalCorrect   *int     `json:"total_correct,omitempty"`

	// Timing
	DurationSeconds *float64 `json:"duration_seconds,omitempty"`

	// Error
	ErrorMessage string `json:"error_message,omitempty"`

	// Comparison
	BaselineRunID           string   `json:"baseline_run_id,omitempty"`
	ImprovementFromBaseline *float64 `json:"improvement_from_baseline,omitempty"`
	IsBestRun               bool     `json:"is_best_run"`

	// Autonomous loop
	AutonomousLoopID  string `json:"autonomous_loop_id,omitempty"`
	IterationNumber   int    `json:"iteration_number"`
	ChangeDescription string `json:"change_description,omitempty"`

	// Metadata
	CreatedBy string `json:"created_by"` // manual, mcp, autonomous
	Notes     string `json:"notes,omitempty"`
}

BenchmarkRun represents a single benchmark execution

type BenchmarkRunFilters 

type BenchmarkRunFilters struct {
	Status        string
	BenchmarkType string
	GitCommit     string
	LoopID        string
	Since         *time.Time
	Until         *time.Time
	Limit         int
	Offset        int
}

BenchmarkRunFilters for querying benchmark runs

type Category 

type Category struct {
	ID                  string    `json:"id"`
	Name                string    `json:"name"`
	Description         string    `json:"description"`
	ParentCategoryID    string    `json:"parent_category_id,omitempty"`
	ConfidenceThreshold float64   `json:"confidence_threshold"`
	AutoGenerated       bool      `json:"auto_generated"`
	CreatedAt           time.Time `json:"created_at"`
}

Category represents a memory category VERIFIED: Matches categories table schema

type Database 

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

Database represents a connection to the SQLite database

func Open 

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

Open opens a database connection and initializes the schema if needed

func (*Database) Begin 

func (d *Database) Begin() (*sql.Tx, error)

Begin starts a new transaction

func (*Database) CategorizeMemory 

func (d *Database) CategorizeMemory(memoryID, categoryID string, confidence float64, reasoning string) error

CategorizeMemory assigns a memory to a category VERIFIED: Matches local-memory categorize behavior

func (*Database) Checkpoint 

func (d *Database) Checkpoint() error

Checkpoint forces a WAL checkpoint

func (*Database) Close 

func (d *Database) Close() error

Close closes the database connection

func (*Database) CountRows 

func (d *Database) CountRows(table string) (int, error)

CountRows returns the number of rows in a table

func (*Database) CreateAutonomousLoop 

func (d *Database) CreateAutonomousLoop(loop *AutonomousLoop) error

CreateAutonomousLoop creates a new autonomous loop record

func (*Database) CreateBenchmarkCategoryResult 

func (d *Database) CreateBenchmarkCategoryResult(result *BenchmarkCategoryResult) error

CreateBenchmarkCategoryResult creates a category result record

func (*Database) CreateBenchmarkQuestionResult 

func (d *Database) CreateBenchmarkQuestionResult(result *BenchmarkQuestionResult) error

CreateBenchmarkQuestionResult creates a question result record

func (*Database) CreateBenchmarkRun 

func (d *Database) CreateBenchmarkRun(run *BenchmarkRun) error

CreateBenchmarkRun creates a new benchmark run record

func (*Database) CreateCategory 

func (d *Database) CreateCategory(c *Category) error

CreateCategory creates a new category VERIFIED: Matches local-memory categories create behavior

func (*Database) CreateDomain 

func (d *Database) CreateDomain(dom *Domain) error

CreateDomain creates a new domain VERIFIED: Matches local-memory domains create behavior

func (*Database) CreateMemory 

func (d *Database) CreateMemory(m *Memory) error

CreateMemory inserts a new memory into the database VERIFIED: Matches local-memory store_memory behavior

func (*Database) CreateRelationship 

func (d *Database) CreateRelationship(r *Relationship) error

CreateRelationship creates a relationship between two memories VERIFIED: Matches local-memory create relationship behavior

func (*Database) DB 

func (d *Database) DB() *sql.DB

DB returns the underlying sql.DB for advanced operations

func (*Database) DeleteMemory 

func (d *Database) DeleteMemory(id string) error

DeleteMemory removes a memory by ID VERIFIED: Matches local-memory delete_memory behavior (CASCADE deletes relationships)

func (*Database) EnsureSession 

func (d *Database) EnsureSession(sessionID string, agentType string) error

EnsureSession creates or updates a session to track it VERIFIED: Matches local-memory session auto-tracking behavior

func (*Database) Exec 

func (d *Database) Exec(query string, args ...interface{}) (sql.Result, error)

Exec executes a SQL statement

func (*Database) FindRelated 

func (d *Database) FindRelated(memoryID string, filters *RelationshipFilters) ([]*Memory, error)

FindRelated finds memories related to a given memory VERIFIED: Matches local-memory find_related behavior

func (*Database) GetAutonomousLoop 

func (d *Database) GetAutonomousLoop(id string) (*AutonomousLoop, error)

GetAutonomousLoop retrieves an autonomous loop by ID

func (*Database) GetBenchmarkCategoryResults 

func (d *Database) GetBenchmarkCategoryResults(runID string) ([]*BenchmarkCategoryResult, error)

GetBenchmarkCategoryResults gets all category results for a run

func (*Database) GetBenchmarkQuestionResults 

func (d *Database) GetBenchmarkQuestionResults(runID string) ([]*BenchmarkQuestionResult, error)

GetBenchmarkQuestionResults retrieves all question results for a run

func (*Database) GetBenchmarkRun 

func (d *Database) GetBenchmarkRun(id string) (*BenchmarkRun, error)

GetBenchmarkRun retrieves a benchmark run by ID

func (*Database) GetBestBenchmarkRun 

func (d *Database) GetBestBenchmarkRun(benchmarkType string) (*BenchmarkRun, error)

GetBestBenchmarkRun returns the best performing run

func (*Database) GetChildChunks 

func (d *Database) GetChildChunks(parentID string) ([]*Memory, error)

GetChildChunks retrieves all chunks belonging to a parent memory

func (*Database) GetDomainStats 

func (d *Database) GetDomainStats(domainName string) (*DomainStats, error)

GetDomainStats retrieves statistics for a specific domain

func (*Database) GetGraph 

func (d *Database) GetGraph(rootID string, depth int) (*Graph, error)

GetGraph retrieves the relationship graph starting from a memory VERIFIED: Matches local-memory map_graph behavior with BFS traversal

func (*Database) GetMemory 

func (d *Database) GetMemory(id string) (*Memory, error)

GetMemory retrieves a memory by ID VERIFIED: Matches local-memory get_memory_by_id behavior

func (*Database) GetMemoryCountBySession 

func (d *Database) GetMemoryCountBySession(sessionID string) (int, error)

GetMemoryCountBySession returns the count of memories for a session

func (*Database) GetRelationshipsBetween 

func (d *Database) GetRelationshipsBetween(sourceID, targetID string) ([]*Relationship, error)

GetRelationshipsBetween gets all relationships between two memories

func (*Database) GetRelationshipsForMemory 

func (d *Database) GetRelationshipsForMemory(memoryID string) ([]*Relationship, error)

GetRelationshipsForMemory gets all relationships for a memory ID

func (*Database) GetRootMemories 

func (d *Database) GetRootMemories(filters *MemoryFilters) ([]*Memory, error)

GetRootMemories retrieves only root memories (not chunks)

func (*Database) GetSchemaVersion 

func (d *Database) GetSchemaVersion() (int, error)

GetSchemaVersion returns the current schema version

func (*Database) GetStats 

func (d *Database) GetStats() (*Stats, error)

GetStats returns database statistics

func (*Database) InitSchema 

func (d *Database) InitSchema() error

InitSchema initializes the database schema This creates all tables, indexes, triggers, and FTS5 configuration

func (*Database) ListBenchmarkRuns 

func (d *Database) ListBenchmarkRuns(filters *BenchmarkRunFilters) ([]*BenchmarkRun, error)

ListBenchmarkRuns retrieves benchmark runs with optional filters

func (*Database) ListCategories 

func (d *Database) ListCategories() ([]*Category, error)

ListCategories retrieves all categories VERIFIED: Matches local-memory categories list behavior

func (*Database) ListDomains 

func (d *Database) ListDomains() ([]*Domain, error)

ListDomains retrieves all domains VERIFIED: Matches local-memory domains list behavior

func (*Database) ListMemories 

func (d *Database) ListMemories(filters *MemoryFilters) ([]*Memory, error)

ListMemories retrieves memories with optional filters VERIFIED: Matches local-memory list behavior with pagination

func (*Database) ListSessions 

func (d *Database) ListSessions() ([]*AgentSession, error)

ListSessions retrieves all sessions VERIFIED: Matches local-memory sessions list behavior

func (*Database) Path 

func (d *Database) Path() string

Path returns the database file path

func (*Database) Query 

func (d *Database) Query(query string, args ...interface{}) (*sql.Rows, error)

Query executes a SQL query and returns rows

func (*Database) QueryRow 

func (d *Database) QueryRow(query string, args ...interface{}) *sql.Row

QueryRow executes a SQL query and returns a single row

func (*Database) RecordMetric 

func (d *Database) RecordMetric(operationType string, executionTimeMs int, memoryCount int) error

RecordMetric records a performance metric VERIFIED: Matches local-memory performance tracking

func (*Database) RunMigrations 

func (d *Database) RunMigrations() error

RunMigrations checks the current schema version and runs any pending migrations

func (*Database) SearchFTS 

func (d *Database) SearchFTS(query string, filters *SearchFilters) ([]*SearchResult, error)

SearchFTS performs full-text search using FTS5 VERIFIED: Matches local-memory keyword search behavior

func (*Database) TableExists 

func (d *Database) TableExists(name string) (bool, error)

TableExists checks if a table exists in the database

func (*Database) UpdateAutonomousLoop 

func (d *Database) UpdateAutonomousLoop(loop *AutonomousLoop) error

UpdateAutonomousLoop updates an existing autonomous loop

func (*Database) UpdateBenchmarkRun 

func (d *Database) UpdateBenchmarkRun(run *BenchmarkRun) error

UpdateBenchmarkRun updates an existing benchmark run

func (*Database) UpdateMemory 

func (d *Database) UpdateMemory(id string, updates *MemoryUpdate) error

UpdateMemory updates an existing memory VERIFIED: Matches local-memory update_memory behavior

func (*Database) Vacuum 

func (d *Database) Vacuum() error

Vacuum runs VACUUM to optimize the database file

type Domain 

type Domain struct {
	ID          string    `json:"id"`
	Name        string    `json:"name"`
	Description string    `json:"description,omitempty"`
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at"`
}

Domain represents a knowledge domain VERIFIED: Matches domains table schema

type DomainStats 

type DomainStats struct {
	MemoryCount       int
	AverageImportance float64
}

DomainStats contains statistics for a domain

type Graph 

type Graph struct {
	Nodes []GraphNode `json:"nodes"`
	Edges []GraphEdge `json:"edges"`
}

Graph represents a memory relationship graph VERIFIED: Output format matches local-memory map_graph command

type GraphEdge 

type GraphEdge struct {
	SourceID string  `json:"source_id"`
	TargetID string  `json:"target_id"`
	Type     string  `json:"type"`
	Strength float64 `json:"strength"`
}

GraphEdge represents an edge in the relationship graph

type GraphNode 

type GraphNode struct {
	ID         string `json:"id"`
	Content    string `json:"content"`
	Importance int    `json:"importance"`
	Distance   int    `json:"distance"` // Distance from source node
}

GraphNode represents a node in the relationship graph

type Memory 

type Memory struct {
	ID           string    `json:"id"`
	Content      string    `json:"content"`
	Source       string    `json:"source,omitempty"`
	Importance   int       `json:"importance"`
	Tags         []string  `json:"tags,omitempty"`
	SessionID    string    `json:"session_id,omitempty"`
	Domain       string    `json:"domain,omitempty"`
	Embedding    []byte    `json:"embedding,omitempty"`
	CreatedAt    time.Time `json:"created_at"`
	UpdatedAt    time.Time `json:"updated_at"`
	AgentType    string    `json:"agent_type"`
	AgentContext string    `json:"agent_context,omitempty"`
	AccessScope  string    `json:"access_scope"`
	Slug         string    `json:"slug,omitempty"`
	// Hierarchical chunking fields (Phase 1 benchmark improvement)
	ParentMemoryID string `json:"parent_memory_id,omitempty"` // ID of parent memory (null for root)
	ChunkLevel     int    `json:"chunk_level"`                // 0=full/root, 1=paragraph, 2=atomic
	ChunkIndex     int    `json:"chunk_index"`                // Position within parent's chunks
}

Memory represents a stored memory VERIFIED: Matches memories table schema from Local Memory v1.2.0

func (*Memory) IsChunk 

func (m *Memory) IsChunk() bool

IsChunk returns true if this memory is a chunk (not a root memory)

func (*Memory) IsRoot 

func (m *Memory) IsRoot() bool

IsRoot returns true if this memory is a root memory (not a chunk)

func (*Memory) TagsJSON 

func (m *Memory) TagsJSON() string

TagsJSON returns tags as JSON string for database storage

type MemoryCategorization 

type MemoryCategorization struct {
	MemoryID   string    `json:"memory_id"`
	CategoryID string    `json:"category_id"`
	Confidence float64   `json:"confidence"` // 0.0 to 1.0
	Reasoning  string    `json:"reasoning,omitempty"`
	CreatedAt  time.Time `json:"created_at"`
}

MemoryCategorization represents the M2M junction between memory and category VERIFIED: Matches memory_categorizations table schema

type MemoryFilters 

type MemoryFilters struct {
	SessionID     string
	Domain        string
	Tags          []string
	MinImportance int
	MaxImportance int
	StartDate     *time.Time
	EndDate       *time.Time
	Limit         int
	Offset        int
}

MemoryFilters represents filters for listing memories

type MemoryUpdate 

type MemoryUpdate struct {
	Content    *string
	Importance *int
	Tags       []string
	Source     *string
	Domain     *string
}

MemoryUpdate represents optional updates to a memory

type MigrationLog 

type MigrationLog struct {
	ID                    string    `json:"id"`
	MigrationType         string    `json:"migration_type"`
	SourceDBPath          string    `json:"source_db_path,omitempty"`
	OriginalSessionID     string    `json:"original_session_id,omitempty"`
	NewSessionID          string    `json:"new_session_id,omitempty"`
	MemoriesMigrated      int       `json:"memories_migrated"`
	RelationshipsMigrated int       `json:"relationships_migrated"`
	CategoriesMigrated    int       `json:"categories_migrated"`
	MigrationTimestamp    time.Time `json:"migration_timestamp"`
	Checksum              string    `json:"checksum,omitempty"`
	Success               bool      `json:"success"`
	ErrorMessage          string    `json:"error_message,omitempty"`
}

MigrationLog represents a database migration record VERIFIED: Matches migration_log table schema

type PerformanceMetric 

type PerformanceMetric struct {
	ID              int       `json:"id"`
	OperationType   string    `json:"operation_type"`
	ExecutionTimeMs int       `json:"execution_time_ms"`
	MemoryCount     int       `json:"memory_count,omitempty"`
	Timestamp       time.Time `json:"timestamp"`
}

PerformanceMetric represents an operation timing record VERIFIED: Matches performance_metrics table schema

type Relationship 

type Relationship struct {
	ID               string    `json:"id"`
	SourceMemoryID   string    `json:"source_memory_id"`
	TargetMemoryID   string    `json:"target_memory_id"`
	RelationshipType string    `json:"relationship_type"` // One of 7 verified types
	Strength         float64   `json:"strength"`          // 0.0 to 1.0
	Context          string    `json:"context,omitempty"`
	AutoGenerated    bool      `json:"auto_generated"`
	CreatedAt        time.Time `json:"created_at"`
}

Relationship represents a connection between two memories VERIFIED: Matches memory_relationships table schema

type RelationshipFilters 

type RelationshipFilters struct {
	Type        string
	MinStrength float64
	Limit       int
}

RelationshipFilters represents filters for finding relationships

type SearchFilters 

type SearchFilters struct {
	Query        string
	SessionID    string
	Domain       string
	Tags         []string
	UseAI        bool // Use semantic search vs FTS5
	Limit        int
	MinRelevance float64
}

SearchFilters represents filters for searching memories

type SearchResult 

type SearchResult struct {
	Memory    *Memory `json:"memory"`
	Relevance float64 `json:"relevance"` // 0.0 to 1.0 (verified: 1.00 = perfect match)
}

SearchResult represents a memory search result with relevance

type Stats 

type Stats struct {
	Path          string
	SchemaVersion int
	TableCount    int
	MemoryCount   int
	RelationCount int
	CategoryCount int
	DomainCount   int
	SessionCount  int
	FileSizeBytes int64
}

Stats returns database statistics

type VectorMetadata 

type VectorMetadata struct {
	MemoryID           string    `json:"memory_id"`
	VectorIndex        int       `json:"vector_index"`
	EmbeddingModel     string    `json:"embedding_model"`
	EmbeddingDimension int       `json:"embedding_dimension"` // 768 for nomic-embed-text
	LastUpdated        time.Time `json:"last_updated"`
}

VectorMetadata represents embedding metadata VERIFIED: Matches vector_metadata table schema

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.