memory

package
v0.0.2 Latest Latest
Warning

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

Go to latest
Published: Oct 11, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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) CommitSummary

func (s *JSONLStore) CommitSummary(
	_ context.Context,
	sessionKey string,
	summarized []providers.Message,
	summary string,
) (bool, error)

CommitSummary stores summary as the session's summary and drops summarized from the start of its history, in one metadata write, provided summarized are still the session's oldest messages. When they are not — the history was cleared, replaced or compacted after they were read — it changes nothing and reports false. Messages appended meanwhile are kept.

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.

type SummaryCommitter

type SummaryCommitter interface {
	CommitSummary(ctx context.Context, sessionKey string, summarized []providers.Message, summary string) (bool, error)
}

SummaryCommitter is implemented by stores that can replace the oldest messages of a session with a summary in one step, provided they are still its oldest messages (see JSONLStore.CommitSummary).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL