memory

Documentation

Index

• type JSONLStore
  • func NewJSONLStore(dir string) (*JSONLStore, error)
  • func (s *JSONLStore) AddFullMessage(_ context.Context, sessionKey string, msg providers.Message) error
  • func (s *JSONLStore) AddMessage(_ context.Context, sessionKey, role, content string) error
  • func (s *JSONLStore) Close() error
  • func (s *JSONLStore) Compact(_ context.Context, sessionKey string) error
  • func (s *JSONLStore) GetHistory(_ context.Context, sessionKey string) ([]providers.Message, error)
  • func (s *JSONLStore) GetSessionMeta(_ context.Context, sessionKey string) (SessionMeta, error)
  • func (s *JSONLStore) GetSummary(_ context.Context, sessionKey string) (string, error)
  • func (s *JSONLStore) ListSessions() []string
  • func (s *JSONLStore) SetHistory(_ context.Context, sessionKey string, history []providers.Message) error
  • func (s *JSONLStore) SetSummary(_ context.Context, sessionKey, summary string) error
  • func (s *JSONLStore) TruncateHistory(_ context.Context, sessionKey string, keepLast int) error
  • func (s *JSONLStore) UpsertSessionMeta(_ context.Context, sessionKey string, scope json.RawMessage) error
• type SessionMeta
• type Store

Types

type JSONLStore

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

JSONLStore implements Store using append-only JSONL files.

Each session is stored as two files:

{sanitized_key}.jsonl      — one JSON-encoded message per line, append-only
{sanitized_key}.meta.json  — session metadata (summary, logical truncation offset)

Messages are never physically deleted from the JSONL file. Instead, TruncateHistory records a "skip" offset in the metadata file and GetHistory ignores lines before that offset. This keeps all writes append-only, which is both fast and crash-safe.

func NewJSONLStore

func NewJSONLStore(dir string) (*JSONLStore, error)

NewJSONLStore creates a new JSONL-backed store rooted at dir, creating the directory when needed. If the directory cannot be created the error is returned together with a store that is still safe to use: it reports no sessions and its writes fail until the directory becomes available.

func (*JSONLStore) AddFullMessage

func (s *JSONLStore) AddFullMessage(
	_ context.Context, sessionKey string, msg providers.Message,
) error

func (*JSONLStore) AddMessage

func (s *JSONLStore) AddMessage(
	_ context.Context, sessionKey, role, content string,
) error

func (*JSONLStore) Close

func (s *JSONLStore) Close() error

func (*JSONLStore) Compact

func (s *JSONLStore) Compact(
	_ context.Context, sessionKey string,
) error

Compact physically rewrites the JSONL file, dropping all logically skipped lines. This reclaims disk space that accumulates after repeated TruncateHistory calls.

It is safe to call at any time; if there is nothing to compact (skip == 0) the method returns immediately.

func (*JSONLStore) GetHistory

func (s *JSONLStore) GetHistory(
	_ context.Context, sessionKey string,
) ([]providers.Message, error)

func (*JSONLStore) GetSessionMeta

func (s *JSONLStore) GetSessionMeta(_ context.Context, sessionKey string) (SessionMeta, error)

GetSessionMeta returns the current metadata snapshot for sessionKey.

func (*JSONLStore) GetSummary

func (s *JSONLStore) GetSummary(
	_ context.Context, sessionKey string,
) (string, error)

func (*JSONLStore) ListSessions

func (s *JSONLStore) ListSessions() []string

ListSessions returns all known session keys by reading .meta.json files.

func (*JSONLStore) SetHistory

func (s *JSONLStore) SetHistory(
	_ context.Context,
	sessionKey string,
	history []providers.Message,
) error

func (*JSONLStore) SetSummary

func (s *JSONLStore) SetSummary(
	_ context.Context, sessionKey, summary string,
) error

func (*JSONLStore) TruncateHistory

func (s *JSONLStore) TruncateHistory(
	_ context.Context, sessionKey string, keepLast int,
) error

func (*JSONLStore) UpsertSessionMeta

func (s *JSONLStore) UpsertSessionMeta(
	_ context.Context,
	sessionKey string,
	scope json.RawMessage,
) error

UpsertSessionMeta stores structured session metadata while preserving summary/count/skip timestamps maintained by the core JSONL store.

type SessionMeta

type SessionMeta struct {
	Key       string          `json:"key"`
	Summary   string          `json:"summary"`
	Skip      int             `json:"skip"`
	Count     int             `json:"count"`
	CreatedAt time.Time       `json:"created_at"`
	UpdatedAt time.Time       `json:"updated_at"`
	Scope     json.RawMessage `json:"scope,omitempty"`
}

SessionMeta holds per-session metadata stored in a .meta.json file.

Scope is stored as raw JSON so pkg/memory can stay decoupled from the higher-level session package while still preserving structured scope data.

type Store

type Store interface {
	// AddMessage appends a simple text message to a session.
	AddMessage(ctx context.Context, sessionKey, role, content string) error

	// AddFullMessage appends a complete message (with tool calls, etc.) to a session.
	AddFullMessage(ctx context.Context, sessionKey string, msg providers.Message) error

	// GetHistory returns all messages for a session in insertion order.
	// Returns an empty slice (not nil) if the session does not exist.
	GetHistory(ctx context.Context, sessionKey string) ([]providers.Message, error)

	// GetSummary returns the conversation summary for a session.
	// Returns an empty string if no summary exists.
	GetSummary(ctx context.Context, sessionKey string) (string, error)

	// SetSummary updates the conversation summary for a session.
	SetSummary(ctx context.Context, sessionKey, summary string) error

	// TruncateHistory removes all but the last keepLast messages from a session.
	// If keepLast <= 0, all messages are removed.
	TruncateHistory(ctx context.Context, sessionKey string, keepLast int) error

	// SetHistory replaces all messages in a session with the provided history.
	SetHistory(ctx context.Context, sessionKey string, history []providers.Message) error

	// Compact reclaims storage by physically removing logically truncated
	// data. Backends that do not accumulate dead data may return nil.
	Compact(ctx context.Context, sessionKey string) error

	// ListSessions returns all known session keys.
	ListSessions() []string

	// Close releases any resources held by the store.
	Close() error
}

Store defines an interface for persistent session storage. Each method is an atomic operation — there is no separate Save() call.