sqlite

README

blades-sqlite

SQLite-backed memory.MemoryStore for github.com/go-kratos/blades.

The store is designed for local agent runtimes and Agent Layouts:

• persists Blades memories to a single SQLite database file
• persists session history with SaveSession
• uses SQLite FTS5 for text search when available
• falls back to case-insensitive LIKE search when FTS5 is disabled or unavailable
• uses the cgo-free modernc.org/sqlite driver
• implements memory.MemoryStore

Install

go get github.com/terminus-io/blades-sqlite

Usage

package main

import (
	"context"

	sqlitememory "github.com/terminus-io/blades-sqlite"
	"github.com/go-kratos/blades"
	"github.com/go-kratos/blades/memory"
)

func main() {
	ctx := context.Background()

	store, err := sqlitememory.Open("agent-memory.db")
	if err != nil {
		panic(err)
	}
	defer store.Close()

	if err := store.AddMemory(ctx, &memory.Memory{
		Content: blades.UserMessage("The user prefers concise Chinese answers."),
		Metadata: map[string]any{
			"memory_type": "preference",
		},
	}); err != nil {
		panic(err)
	}

	results, err := store.SearchMemory(ctx, "Chinese answers")
	if err != nil {
		panic(err)
	}
	_ = results

	session := blades.NewSession()
	_ = session.Append(ctx, blades.UserMessage("Remember this session message."))
	if err := store.SaveSession(ctx, session); err != nil {
		panic(err)
	}
}

To expose memory search as a Blades tool:

memoryTool, err := memory.NewMemoryTool(store)
if err != nil {
	panic(err)
}

Options

store, err := sqlitememory.Open(
	"agent-memory.db",
	sqlitememory.WithLimit(5),
	sqlitememory.WithFTS(true),
)

WithFTS(true) is the default. If SQLite FTS5 initialization fails, the store continues with LIKE search.

Stored Data

The current Blades memory API stores:

type MemoryStore interface {
	AddMemory(context.Context, *memory.Memory) error
	SaveSession(context.Context, blades.Session) error
	SearchMemory(context.Context, string) ([]*memory.Memory, error)
}

Blades messages contain interface-typed parts, so this store persists the searchable text from Content.Text() plus message role, author, status, message metadata, and memory metadata. Search results reconstruct a text message with those fields.

SaveSession stores each non-empty text message from session.History(ctx) as a memory with metadata:

session_id
message_index
memory_type=session_message

Saving the same session repeatedly updates existing rows for the same session_id and message id instead of duplicating them.

Test

go test ./...

Documentation

Index

• type Option
  • func WithFTS(enabled bool) Option
  • func WithLimit(limit int) Option
  • func WithNow(now func() time.Time) Option
• type Store
  • func New(db *sql.DB, opts ...Option) (*Store, error)
  • func Open(path string, opts ...Option) (*Store, error)
  • func (s *Store) AddMemory(ctx context.Context, m *memory.Memory) error
  • func (s *Store) Close() error
  • func (s *Store) SaveSession(ctx context.Context, session blades.Session) error
  • func (s *Store) SearchMemory(ctx context.Context, query string) ([]*memory.Memory, error)

Types

type Option

type Option func(*Store)

Option configures Store.

func WithFTS

func WithFTS(enabled bool) Option

WithFTS controls whether the store should try to use SQLite FTS5.

func WithLimit

func WithLimit(limit int) Option

WithLimit sets the maximum number of memories returned by SearchMemory.

func WithNow

func WithNow(now func() time.Time) Option

WithNow overrides the clock used for created_at timestamps.

type Store

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

Store persists Blades memories in SQLite.

func New

func New(db *sql.DB, opts ...Option) (*Store, error)

New creates a Store around an existing *sql.DB and initializes the schema.

func Open

func Open(path string, opts ...Option) (*Store, error)

Open opens a SQLite database at path and initializes the memory schema.

func (*Store) AddMemory

func (s *Store) AddMemory(ctx context.Context, m *memory.Memory) error

AddMemory stores a memory.

func (*Store) Close

func (s *Store) Close() error

Close closes the underlying database when Store opened it.

func (*Store) SaveSession

func (s *Store) SaveSession(ctx context.Context, session blades.Session) error

SaveSession stores the current session history as searchable memories.

func (*Store) SearchMemory

func (s *Store) SearchMemory(ctx context.Context, query string) ([]*memory.Memory, error)

SearchMemory searches memories by text. It uses FTS5 when available and falls back to case-insensitive LIKE matching otherwise.