Documentation
¶
Index ¶
- type JSONLStore
- 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) CommitSummary(_ context.Context, sessionKey string, summarized []providers.Message, ...) (bool, 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
- type SummaryCommitter
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 (*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 (*JSONLStore) GetSessionMeta ¶
func (s *JSONLStore) GetSessionMeta(_ context.Context, sessionKey string) (SessionMeta, error)
GetSessionMeta returns the current metadata snapshot for sessionKey.
func (*JSONLStore) GetSummary ¶
func (*JSONLStore) ListSessions ¶
func (s *JSONLStore) ListSessions() []string
ListSessions returns all known session keys by reading .meta.json files.
func (*JSONLStore) SetHistory ¶
func (*JSONLStore) SetSummary ¶
func (s *JSONLStore) SetSummary( _ context.Context, sessionKey, summary string, ) error
func (*JSONLStore) TruncateHistory ¶
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).