memory

package
v0.0.0-...-88bd7a9 Latest Latest
Warning

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

 Go to latest Published: Aug 27, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Index

Constants

View Source 
const (

	// Default window size: 1 hour in seconds
	DefaultWindowSize int64 = 3600
)

Variables

View Source 
var (
	ErrVectorSearchNotSupported = fmt.Errorf("vector search not supported")
)

Vector search errors.

View Source 
var LowValueEventTypes = map[string]bool{
	event.TypeThinkingPlan:    true,
	event.TypeContextCompress: true,
}

LowValueEventTypes are event types whose Content/ToolCalls can be discarded in L3.

Functions

func EventKeyStr 

func EventKeyStr(pid int, windowTS int64, seq int) string

EventKeyStr builds the RocksDB key for storing event content. Format: {pid}:evt:{window_ts}:{seq}

func EventPrefix 

func EventPrefix(pid int) string

EventPrefix returns the prefix for all event keys in a partition.

func IndexKeyStr 

func IndexKeyStr(pid int, eventKey int64) string

IndexKeyStr builds the RocksDB key for the segment offset index. Format: {pid}:idx:{event_key}

func MetaKeyStr 

func MetaKeyStr(pid int, windowTS int64) string

MetaKeyStr builds the RocksDB key for segment metadata. Format: {pid}:meta:{window_ts}

func MetaPrefix 

func MetaPrefix(pid int) string

MetaPrefix returns the prefix for all meta keys in a partition. Scanning this prefix returns all segment metadata entries.

func NewPartitionID 

func NewPartitionID() int

NewPartitionID generates a unique PartitionID using an atomic counter. Use when no stable name is available for PartitionIDFromName.

func NewSnowflakeEventKey 

func NewSnowflakeEventKey(partitionID int, nowMs int64) int64

NewSnowflakeEventKey generates a Snowflake-style int64 EventKey. partitionID: storage partition (0-2047), provided by caller. nowMs: current time in milliseconds (0 = use time.Now).

func PartitionIDFromEventKey 

func PartitionIDFromEventKey(key int64) int

PartitionIDFromEventKey extracts the PartitionID from a Snowflake EventKey.

func PartitionIDFromName 

func PartitionIDFromName(name string) int

PartitionIDFromName computes a stable PartitionID from a name string.

func PartitionPrefix 

func PartitionPrefix(pid int) string

PartitionPrefix returns the prefix for all keys in a partition.

func SegmentEventPrefix 

func SegmentEventPrefix(pid int, windowTS int64) string

SegmentEventPrefix returns the prefix for events within a specific time window. Scanning this prefix returns all events in the segment.

func SequenceFromEventKey 

func SequenceFromEventKey(key int64) int

SequenceFromEventKey extracts the sequence number from a Snowflake EventKey.

func TimestampFromEventKey 

func TimestampFromEventKey(key int64) int64

TimestampFromEventKey extracts the Unix timestamp (seconds) from a Snowflake EventKey.

func TombstoneKeyStr 

func TombstoneKeyStr(pid int, eventKey int64) string

TombstoneKeyStr builds the RocksDB key for a tombstone marker. Format: {pid}:tomb:{event_key}

func TombstonePrefix 

func TombstonePrefix(pid int) string

TombstonePrefix returns the prefix for all tombstone keys in a partition.

func WindowTimestamp 

func WindowTimestamp(tsSec int64, windowSize int64) int64

WindowTimestamp computes the time window start (epoch seconds) for a given timestamp. Aligns timestamp to window boundaries: floor(timestamp / windowSize) * windowSize.

func WindowTimestampFromEventKey 

func WindowTimestampFromEventKey(eventKey int64, windowSize int64) int64

WindowTimestampFromEventKey computes the window timestamp from an EventKey's embedded timestamp.

Types

type CLIResponse 

type CLIResponse struct {
	Success bool            `json:"success"`
	Data    json.RawMessage `json:"data,omitempty"`
	Error   string          `json:"error,omitempty"`
}

CLIResponse 表示 RustViking CLI 的统一 JSON 响应。

type CompactionConfig 

type CompactionConfig struct {
	L1Threshold   int           // L1 segments before L1→L2 compaction (default: 24)
	L2Threshold   int           // L2 segments before L2→L3 compaction (default: 7)
	CheckInterval time.Duration // How often to check for compaction (default: 5min)
}

CompactionConfig configures the compactor behavior.

func DefaultCompactionConfig 

func DefaultCompactionConfig() CompactionConfig

DefaultCompactionConfig returns the default compaction configuration.

type Compactor 

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

Compactor manages background compaction operations.

func NewCompactor 

func NewCompactor(store *FileSegmentStore, kv KVStore, rel RelationStore, tombstone *TombstoneSet, config CompactionConfig) *Compactor

NewCompactor creates a new Compactor.

func (*Compactor) CompactL1ToL2 

func (c *Compactor) CompactL1ToL2(pid int, windowTSs []int64) error

CompactL1ToL2 compacts L1 hourly segments into a single L2 daily segment for a partition.

func (*Compactor) CompactL2ToL3 

func (c *Compactor) CompactL2ToL3(pid int, windowTSs []int64) error

CompactL2ToL3 compacts L2 daily segments into a single L3 weekly segment. In addition to L1→L2 steps, it summarizes low-value events.

func (*Compactor) Start 

func (c *Compactor) Start()

Start starts the compaction scheduler in a background goroutine.

func (*Compactor) Stop 

func (c *Compactor) Stop()

Stop stops the compaction scheduler gracefully.

type EventReference 

type EventReference struct {
	EventKey     int64  `json:"event_key"`              // Snowflake int64 EventKey
	PartitionID  int    `json:"partition_id,omitempty"` // Storage partition key
	EventType    string `json:"event_type"`             // Event type
	EventSummary string `json:"event_summary"`          // Brief summary of event result
	Timestamp    int64  `json:"timestamp"`              // Unix timestamp in milliseconds
	Role         string `json:"role,omitempty"`         // Original message role (user/assistant/tool/system)
}

EventReference is a lightweight reference to an event stored in MemoryStore. Session only keeps EventReference list, not full event details.

type FileSegmentStore 

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

FileSegmentStore implements MemoryStore using RustViking KV + segment model.

func NewFileSegmentStore 

func NewFileSegmentStore(kv KVStore, rel RelationStore, dataDir string, cacheSize int) (*FileSegmentStore, error)

NewFileSegmentStore creates a FileSegmentStore.

func (*FileSegmentStore) Close 

func (s *FileSegmentStore) Close() error

Close stops all background components (Compactor, LifecycleManager) and closes the RelationStore if it supports closing. Idempotent via sync.Once.

func (*FileSegmentStore) DeleteEvent 

func (s *FileSegmentStore) DeleteEvent(key int64) error

DeleteEvent permanently deletes an event from storage.

func (*FileSegmentStore) GetEvent 

func (s *FileSegmentStore) GetEvent(key int64) (*FullEvent, error)

GetEvent retrieves a single event by its EventKey.

func (*FileSegmentStore) GetEvents 

func (s *FileSegmentStore) GetEvents(keys []int64) ([]FullEvent, error)

GetEvents retrieves multiple events by their EventKeys.

func (*FileSegmentStore) GetSegmentMeta 

func (s *FileSegmentStore) GetSegmentMeta(pid int, windowTS int64) (*SegmentMeta, error)

GetSegmentMeta retrieves segment metadata from KV.

func (*FileSegmentStore) GetStats 

func (s *FileSegmentStore) GetStats() StoreStats

GetStats returns storage statistics.

func (*FileSegmentStore) Init 

func (s *FileSegmentStore) Init() error

Init initializes the FileSegmentStore by scanning existing KV data and recovering partition states. Called on startup after crash recovery.

func (*FileSegmentStore) ListSegments 

func (s *FileSegmentStore) ListSegments(pid int) ([]int64, error)

ListSegments returns all segment window timestamps for a partition.

func (*FileSegmentStore) QueryEvents 

func (s *FileSegmentStore) QueryEvents(query QueryOptions) ([]EventReference, error)

QueryEvents queries events based on filters.

Behavioral contract (segment-query-recency): the result is semantically equivalent to "filter all events → total-order sort → offset/limit". Segmentation, window pruning and early-stop below are optimizations only and must not change the observable result. Total order: (Timestamp, EventKey) — same-millisecond events are tie-broken by EventKey so any two runs (and any store implementation) return identical sequences.

func (*FileSegmentStore) RelationStore 

func (s *FileSegmentStore) RelationStore() RelationStore

RelationStore returns the underlying RelationStore for relationship operations.

func (*FileSegmentStore) SealCurrent 

func (s *FileSegmentStore) SealCurrent(pid int) error

SealCurrent seals the current active segment for a partition. Updates segment metadata in KV to mark it as L1 (sealed).

func (*FileSegmentStore) SearchByEmbedding 

func (s *FileSegmentStore) SearchByEmbedding(query []float32, topK int) ([]EventReference, error)

SearchByEmbedding performs semantic search (stub — not supported).

func (*FileSegmentStore) SetCompactor 

func (s *FileSegmentStore) SetCompactor(c *Compactor)

SetCompactor injects a Compactor for graceful shutdown. The compactor is stopped when Close() is called.

func (*FileSegmentStore) SetLifecycleManager 

func (s *FileSegmentStore) SetLifecycleManager(lm *LifecycleManager)

SetLifecycleManager injects a LifecycleManager for graceful shutdown. The manager is stopped when Close() is called.

func (*FileSegmentStore) SetTombstoneSet 

func (s *FileSegmentStore) SetTombstoneSet(ts *TombstoneSet)

SetTombstoneSet injects a TombstoneSet into the store after construction. This allows tombstone filtering to be enabled without modifying NewFileSegmentStore's signature. Once set, GetEvent and QueryEvents will skip tombstoned events.

func (*FileSegmentStore) StoreEvent 

func (s *FileSegmentStore) StoreEvent(key int64, event FullEvent) error

StoreEvent stores a single event via RustViking KV.

func (*FileSegmentStore) StoreEventWithEmbedding 

func (s *FileSegmentStore) StoreEventWithEmbedding(key int64, event FullEvent, embedding []float32) error

StoreEventWithEmbedding stores event with embedding (stub — ignores embedding).

func (*FileSegmentStore) SupportsVectorSearch 

func (s *FileSegmentStore) SupportsVectorSearch() bool

SupportsVectorSearch returns false.

type FullEvent 

type FullEvent struct {
	EventKey     int64                  `json:"event_key"`         // Snowflake int64 unique identifier
	PartitionID  int                    `json:"partition_id"`      // Storage partition key
	EventType    string                 `json:"event_type"`        // Event type
	EventSummary string                 `json:"event_summary"`     // Brief summary (for LLM context)
	Timestamp    int64                  `json:"timestamp"`         // Unix timestamp (ms)
	Content      string                 `json:"content"`           // Event content/text
	ToolCalls    []model.ToolCall       `json:"tool_calls"`        // Tool calls (if any)
	ToolID       string                 `json:"tool_id,omitempty"` // For a tool-result event: the tool_call id it answers (preserves pairing across store→resolve)
	ToolResults  map[string]interface{} `json:"tool_results"`      // Tool execution results
	Metadata     map[string]string      `json:"metadata"`          // Additional metadata

	// Response field stores the LLM response snapshot (optional)
	Response *model.Response `json:"response,omitempty"`
}

FullEvent represents a complete event with all details stored in MemoryStore. This is the single source of truth for event data.

TIME CONTRACT (segment-query-recency D8) — two timestamps exist, with strictly separated roles:

  • `Timestamp` (this struct) is the SINGLE semantic time axis: ordering, time-range filtering, TTL age and card timelines read ONLY this. It is the moment the event happened.
  • The time embedded in `EventKey` (Snowflake, see NewSnowflakeEventKey) is the moment the event was WRITTEN. It is used only to place the event in a segment window and to break ties between same-millisecond events in the total order — never for semantic time decisions.

The two may diverge for asynchronous events (task_settled write-back, batched delivery). That divergence is harmless precisely because no decision depends on both: it only affects WHICH SEGMENT holds the event, and segment placement carries no semantics (see the segment-vs-time-unit note in docs/wiki/memory/memory-architecture.md §16.3).

Note: ParentKey has been removed from this struct. Event causal relationships are now maintained by RelationStore, accessible via MemoryStore.RelationStore() method (if the store implements RelationStoreProvider). This separates immutable event content from mutable relationships.

type InMemRelationStore 

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

InMemRelationStore 实现了 RelationStore 接口。 内存双图（childToParent + parentToChildren）+ WAL journal。

func NewInMemRelationStore 

func NewInMemRelationStore(dataDir string) (*InMemRelationStore, error)

NewInMemRelationStore 创建并初始化 InMemRelationStore。 dataDir 用于存储 journal 和 snapshot 文件。

func (*InMemRelationStore) Close 

func (rs *InMemRelationStore) Close() error

Close 关闭 store，释放资源。

func (*InMemRelationStore) EventsCount 

func (rs *InMemRelationStore) EventsCount() int

EventsCount 返回当前记录的事件数。

func (*InMemRelationStore) GetChildren 

func (rs *InMemRelationStore) GetChildren(parentKey int64) ([]int64, error)

GetChildren 获取 parentKey 的所有直接后继。

func (*InMemRelationStore) GetParent 

func (rs *InMemRelationStore) GetParent(childKey int64) (int64, error)

GetParent 获取 childKey 的 parentKey。

func (*InMemRelationStore) GetParents 

func (rs *InMemRelationStore) GetParents(keys []int64) (map[int64]int64, error)

GetParents 批量获取 parentKey。

func (*InMemRelationStore) LoadSnapshot 

func (rs *InMemRelationStore) LoadSnapshot(data map[int64]int64) error

LoadSnapshot 从快照恢复。

func (*InMemRelationStore) RemoveRelations 

func (rs *InMemRelationStore) RemoveRelations(key int64) error

RemoveRelations 删除某事件的所有关联。

func (*InMemRelationStore) ReplayJournal 

func (rs *InMemRelationStore) ReplayJournal(entries []JournalEntry) error

ReplayJournal 重放 WAL。

func (*InMemRelationStore) SaveSnapshotToFile 

func (rs *InMemRelationStore) SaveSnapshotToFile() error

SaveSnapshotToFile 将当前关系图的快照保存到文件。 同时截断 journal（snapshot 后所有变更已固化）。

func (*InMemRelationStore) SetParent 

func (rs *InMemRelationStore) SetParent(childKey, parentKey int64) error

SetParent 设置/更新 parentKey。

func (*InMemRelationStore) Snapshot 

func (rs *InMemRelationStore) Snapshot() (map[int64]int64, error)

Snapshot 创建全量快照。

type InMemoryStore 

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

InMemoryStore implements MemoryStore using an in-memory map. Events are partitioned by PartitionID for storage isolation. Suitable for testing and prototyping.

Note: InMemoryStore embeds RelationStore to provide O(1) parent/child relationship queries via GetParent/GetChildren.

func NewInMemoryStore 

func NewInMemoryStore() *InMemoryStore

NewInMemoryStore creates a new InMemoryStore.

func NewInMemoryStoreWithRelation 

func NewInMemoryStoreWithRelation(rel RelationStore) *InMemoryStore

NewInMemoryStoreWithRelation creates a new InMemoryStore with a RelationStore. If rel is nil, creates a default simpleInMemRelationStore that stores relationships in memory.

func (*InMemoryStore) AllEvents 

func (s *InMemoryStore) AllEvents() []FullEvent

AllEvents returns all stored events (for testing/debugging).

func (*InMemoryStore) AllEventsByPartition 

func (s *InMemoryStore) AllEventsByPartition(partitionID int) []FullEvent

AllEventsByPartition returns events for a specific partition (for testing/debugging).

func (*InMemoryStore) DeleteEvent 

func (s *InMemoryStore) DeleteEvent(key int64) error

DeleteEvent permanently deletes an event.

func (*InMemoryStore) GetChildren 

func (s *InMemoryStore) GetChildren(key int64) ([]int64, error)

GetChildren returns all direct child EventKeys for the given event key.

func (*InMemoryStore) GetEvent 

func (s *InMemoryStore) GetEvent(key int64) (*FullEvent, error)

GetEvent retrieves a single event by its EventKey.

func (*InMemoryStore) GetEvents 

func (s *InMemoryStore) GetEvents(keys []int64) ([]FullEvent, error)

GetEvents retrieves multiple events by their EventKeys.

func (*InMemoryStore) GetParent 

func (s *InMemoryStore) GetParent(key int64) (int64, error)

GetParent returns the parent EventKey for the given event key.

func (*InMemoryStore) GetStats 

func (s *InMemoryStore) GetStats() StoreStats

GetStats returns storage statistics.

func (*InMemoryStore) QueryEvents 

func (s *InMemoryStore) QueryEvents(query QueryOptions) ([]EventReference, error)

QueryEvents queries events based on filters.

func (*InMemoryStore) RelationStore 

func (s *InMemoryStore) RelationStore() RelationStore

RelationStore returns the underlying RelationStore for relationship operations. This is used by higher-level components (e.g., plugin) to manage parent-child relationships independently of CRUD operations.

func (*InMemoryStore) SearchByEmbedding 

func (s *InMemoryStore) SearchByEmbedding(query []float32, topK int) ([]EventReference, error)

SearchByEmbedding performs semantic search (stub — not supported).

func (*InMemoryStore) SetParent 

func (s *InMemoryStore) SetParent(key int64, parentKey int64) error

SetParent sets the parent EventKey for the given event key.

func (*InMemoryStore) StoreEvent 

func (s *InMemoryStore) StoreEvent(key int64, event FullEvent) error

StoreEvent stores a single event.

func (*InMemoryStore) StoreEventWithEmbedding 

func (s *InMemoryStore) StoreEventWithEmbedding(key int64, event FullEvent, embedding []float32) error

StoreEventWithEmbedding stores event with embedding (stub — ignores embedding).

func (*InMemoryStore) SupportsVectorSearch 

func (s *InMemoryStore) SupportsVectorSearch() bool

SupportsVectorSearch returns false for InMemoryStore.

type JournalEntry 

type JournalEntry struct {
	Op        string // "+1" = SetParent, "-1" = RemoveRelations
	ChildKey  int64  // meaningful for SetParent
	ParentKey int64  // meaningful for SetParent
	EventKey  int64  // meaningful for RemoveRelations
}

JournalEntry 表示一条 WAL 日志记录。

type KVOp 

type KVOp struct {
	Type  string `json:"op"` // "put" or "delete"
	Key   string `json:"key"`
	Value string `json:"value,omitempty"`
}

KVOp 表示一个批量操作。

type KVPair 

type KVPair struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

KVPair 表示一个键值对。

type KVStore 

type KVStore interface {
	KVPut(key, value string) error
	KVGet(key string) (string, error)
	KVDelete(key string) error
	KVScan(prefix string, limit int) ([]KVPair, error)
	KVRange(start, end string, limit int) ([]KVPair, error)
	KVBatch(ops []KVOp) error
}

KVStore 接口抽象了 RustViking KV 操作，便于测试时替换。

type LifecycleConfig 

type LifecycleConfig struct {
	// GlobalTTLDays is the default TTL for all events (default: 7).
	GlobalTTLDays int `json:"global_ttl_days"`
	// MaxEventsPerPartition is the maximum event count per partition (0 = no limit).
	MaxEventsPerPartition int `json:"max_events_per_partition"`
	// CheckInterval is how often to check for expired events (default: 1 hour).
	CheckInterval time.Duration `json:"check_interval"`
	// TypeTTL overrides global TTL for specific event types (in days).
	// Key = event type, Value = TTL in days.
	TypeTTL map[string]int `json:"type_ttl,omitempty"`
}

LifecycleConfig configures the lifecycle manager.

func DefaultLifecycleConfig 

func DefaultLifecycleConfig() LifecycleConfig

DefaultLifecycleConfig returns the default lifecycle configuration.

type LifecycleManager 

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

LifecycleManager manages event TTL expiration and capacity eviction.

func NewLifecycleManager 

func NewLifecycleManager(store *FileSegmentStore, tombstone *TombstoneSet, config LifecycleConfig) *LifecycleManager

NewLifecycleManager creates a LifecycleManager.

func (*LifecycleManager) GetTombstoneFilterFunc 

func (lm *LifecycleManager) GetTombstoneFilterFunc() func(int64) bool

GetTombstoneFilterFunc returns a filter function for compaction that checks if an event key is tombstoned.

func (*LifecycleManager) Start 

func (lm *LifecycleManager) Start()

Start starts the lifecycle manager background goroutine.

func (*LifecycleManager) Stop 

func (lm *LifecycleManager) Stop()

Stop stops the lifecycle manager gracefully.

type LocalFileKV 

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

LocalFileKV is a file-backed KVStore with a snapshot + WAL layout: 

kv.json      — full-map snapshot (rewritten only at compaction)
kv.wal.jsonl — append-only op log, one JSON op per line

Writes update the in-memory map immediately (reads are always consistent) and enqueue an op; the op buffer is appended to the WAL every flushInterval or every flushThreshold writes. Appending is O(pending ops) — the full map is NOT reserialized per flush (the old single-file layout rewrote the entire store every flush, which grew O(n) with history: 33MB per 2s on a long-lived deployment).

Compaction (snapshot rewrite + WAL truncate) triggers only when the WAL exceeds compactWALBytes, amortizing the O(n) cost over megabytes of appends. Startup loads the snapshot then replays the WAL; a torn final line from a crash is tolerated (ignored).

The physical layout thus aligns with the store's logical model: hot increments append (like L0 window writes), full rewrites happen only at compaction points (like segment sealing) — not on every flush.

It has no external binary dependencies (unlike RustVikingClient which requires the rustviking CLI).

func NewLocalFileKV 

func NewLocalFileKV(dataDir string) (*LocalFileKV, error)

NewLocalFileKV creates a LocalFileKV backed by kv.json (snapshot) and kv.wal.jsonl (op log) in the given dataDir. Existing data is loaded on startup: snapshot first, then WAL replay (torn tail lines from a crash are ignored). Directories and leftover .tmp files are handled. A background goroutine periodically flushes pending ops.

Backward compatible with the previous single-file layout: an old kv.json simply loads as the snapshot (no WAL present).

func (*LocalFileKV) Close 

func (k *LocalFileKV) Close() error

Close flushes pending ops and stops the background flush goroutine. The final flush is performed synchronously so callers get a durability guarantee: when Close returns, all acknowledged writes are on disk. After Close, the KV is no longer usable.

func (*LocalFileKV) Compact 

func (k *LocalFileKV) Compact() error

Compact forces a snapshot rewrite + WAL truncation regardless of WAL size.

func (*LocalFileKV) KVBatch 

func (k *LocalFileKV) KVBatch(ops []KVOp) error

KVBatch applies a batch of put/delete operations atomically and persists them asynchronously.

func (*LocalFileKV) KVDelete 

func (k *LocalFileKV) KVDelete(key string) error

KVDelete removes a key. The change is persisted asynchronously.

func (*LocalFileKV) KVGet 

func (k *LocalFileKV) KVGet(key string) (string, error)

KVGet retrieves the value for a key. Returns an error if the key does not exist.

func (*LocalFileKV) KVPut 

func (k *LocalFileKV) KVPut(key, value string) error

KVPut stores a key-value pair. The write is persisted to the WAL asynchronously (within flushInterval) or immediately when the write threshold is reached.

func (*LocalFileKV) KVRange 

func (k *LocalFileKV) KVRange(start, end string, limit int) ([]KVPair, error)

KVRange returns all key-value pairs whose keys fall in [start, end), sorted lexicographically by key. If limit > 0, at most limit pairs are returned.

func (*LocalFileKV) KVScan 

func (k *LocalFileKV) KVScan(prefix string, limit int) ([]KVPair, error)

KVScan returns all key-value pairs whose keys start with the given prefix, sorted lexicographically by key. If limit > 0, at most limit pairs are returned.

func (*LocalFileKV) Sync 

func (k *LocalFileKV) Sync() error

Sync forces an immediate append of pending ops to the WAL. Safe to call concurrently.

type MemoryStore 

type MemoryStore interface {

	// StoreEvent stores a single event with its full details.
	StoreEvent(key int64, event FullEvent) error

	// GetEvent retrieves a single event by its EventKey.
	GetEvent(key int64) (*FullEvent, error)

	// GetEvents retrieves multiple events by their EventKeys.
	// Returns events in the same order as keys. Skips missing keys.
	GetEvents(keys []int64) ([]FullEvent, error)

	// QueryEvents queries events based on filters.
	// Returns EventReference list (lightweight).
	QueryEvents(query QueryOptions) ([]EventReference, error)

	// SearchByEmbedding performs semantic search using a query embedding.
	SearchByEmbedding(query []float32, topK int) ([]EventReference, error)

	// StoreEventWithEmbedding stores an event with its vector embedding.
	StoreEventWithEmbedding(key int64, event FullEvent, embedding []float32) error

	// SupportsVectorSearch returns true if this store supports vector operations.
	SupportsVectorSearch() bool

	// DeleteEvent permanently deletes an event from storage.
	DeleteEvent(key int64) error

	// GetStats returns storage statistics.
	GetStats() StoreStats
}

MemoryStore is the interface for event storage and retrieval. It serves as the single source of truth for all event data.

Storage isolation: MemoryStore uses PartitionID as the storage partition key. Memory does not know about agents — PartitionID is a pure storage concept. The mapping from agent identity → PartitionID happens outside MemoryStore (in MemoryPlugin), keeping Memory's storage semantics clean.

type MockRustVikingClient 

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

MockRustVikingClient 是 RustVikingClient 的内存 mock，用于开发和测试。

func NewMockRustVikingClient 

func NewMockRustVikingClient() *MockRustVikingClient

NewMockRustVikingClient 创建 MockRustVikingClient。

func (*MockRustVikingClient) KVBatch 

func (m *MockRustVikingClient) KVBatch(ops []KVOp) error

func (*MockRustVikingClient) KVDelete 

func (m *MockRustVikingClient) KVDelete(key string) error

func (*MockRustVikingClient) KVGet 

func (m *MockRustVikingClient) KVGet(key string) (string, error)

func (*MockRustVikingClient) KVPut 

func (m *MockRustVikingClient) KVPut(key, value string) error

func (*MockRustVikingClient) KVRange 

func (m *MockRustVikingClient) KVRange(start, end string, limit int) ([]KVPair, error)

func (*MockRustVikingClient) KVScan 

func (m *MockRustVikingClient) KVScan(prefix string, limit int) ([]KVPair, error)

type ParsedKey 

type ParsedKey struct {
	PartitionID int
	KeyType     string // "evt", "idx", "meta", "tomb"
	WindowTS    int64  // meaningful for evt, meta keys
	Seq         int    // meaningful for evt keys
	EventKey    int64  // meaningful for idx, tomb keys
}

ParsedKey contains the components extracted from a KV key.

func ParseKey 

func ParseKey(key string) (*ParsedKey, error)

ParseKey parses a KV key string into its components. Returns error if the key format is invalid.

type PartitionState 

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

PartitionState holds per-partition state for FileSegmentStore.

type QueryOptions 

type QueryOptions struct {
	// PartitionID filters events by storage partition.
	// 0 = no partition filter (query across all partitions).
	PartitionID int `json:"partition_id"`
	// PartitionIDs filters events across multiple partitions.
	// Takes precedence over PartitionID if non-empty.
	PartitionIDs []int    `json:"partition_ids"`
	EventTypes   []string `json:"event_types"`
	// StartTime/EndTime filter events by timestamp, in Unix MILLISECONDS
	// (same unit as FullEvent.Timestamp and the recall tools' since/until).
	// Zero = no bound.
	StartTime int64  `json:"start_time"`
	EndTime   int64  `json:"end_time"`
	Limit     int    `json:"limit"`
	Offset    int    `json:"offset"`
	OrderBy   string `json:"order_by"`
	// Keyword filters events whose EventSummary or Content contains the keyword (case-insensitive).
	// Empty string = no keyword filter.
	Keyword string `json:"keyword,omitempty"`
}

QueryOptions specifies filters for querying events.

type RelationStore 

type RelationStore interface {
	// SetParent 设置/更新 parentKey（建立或修改因果链）
	SetParent(childKey, parentKey int64) error

	// GetParent 获取 parentKey（0 = 无前驱）
	GetParent(childKey int64) (int64, error)

	// GetChildren 获取所有直接后继（反向查询）
	GetChildren(parentKey int64) ([]int64, error)

	// GetParents 批量获取（memory_trace 热路径优化）
	GetParents(keys []int64) (map[int64]int64, error)

	// RemoveRelations 删除某事件的所有关联（逐出时调用）
	RemoveRelations(key int64) error

	// Snapshot 创建全量快照
	Snapshot() (map[int64]int64, error)

	// LoadSnapshot 从快照恢复
	LoadSnapshot(data map[int64]int64) error

	// ReplayJournal 重放 WAL（启动恢复）
	ReplayJournal(entries []JournalEntry) error

	// EventsCount 返回当前记录的事件数
	EventsCount() int
}

RelationStore 维护事件间的因果关联图。 全量常驻内存，变更通过 WAL 持久化。

type RelationStoreProvider 

type RelationStoreProvider interface {
	RelationStore() RelationStore
}

RelationStoreProvider is an optional interface for MemoryStore implementations that support causal relationship management via RelationStore. Callers should type-assert MemoryStore to RelationStoreProvider before accessing parent/child relationships, as not all implementations expose relation operations.

type RustVikingClient 

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

RustVikingClient 封装对 rustviking CLI 的调用。

func NewRustVikingClient 

func NewRustVikingClient(binaryPath, configPath string) *RustVikingClient

NewRustVikingClient 创建 RustVikingClient。 binaryPath: rustviking 二进制路径（空值使用 "rustviking"） configPath: 配置文件路径（config.toml），用于指定存储目录等设置

func (*RustVikingClient) Embed 

func (c *RustVikingClient) Embed(texts []string) ([][]float32, error)

Embed 文本转向量。

func (*RustVikingClient) KVBatch 

func (c *RustVikingClient) KVBatch(ops []KVOp) error

KVBatch 批量写入（通过 stdin pipe）。 rustviking 期望 JSON 格式: [{"op":"put","key":"k1","value":"v1"},{"op":"delete","key":"k2"}]

func (*RustVikingClient) KVDelete 

func (c *RustVikingClient) KVDelete(key string) error

KVDelete 删除单个 KV。

func (*RustVikingClient) KVGet 

func (c *RustVikingClient) KVGet(key string) (string, error)

KVGet 获取单个 KV 的值。 注意: rustviking CLI 在 key 不存在时返回 null value（而非错误）。

func (*RustVikingClient) KVPut 

func (c *RustVikingClient) KVPut(key, value string) error

KVPut 写入单个 KV。

func (*RustVikingClient) KVRange 

func (c *RustVikingClient) KVRange(start, end string, limit int) ([]KVPair, error)

KVRange 范围扫描。 注意: rustviking CLI 不直接支持 range 操作，使用 KVScan 扫描公共前缀后过滤。

func (*RustVikingClient) KVScan 

func (c *RustVikingClient) KVScan(prefix string, limit int) ([]KVPair, error)

KVScan 前缀扫描。

func (*RustVikingClient) VectorInsert 

func (c *RustVikingClient) VectorInsert(id uint64, vector []float32, level uint8) error

VectorInsert 插入向量。

func (*RustVikingClient) VectorSearch 

func (c *RustVikingClient) VectorSearch(query []float32, k int) ([]uint64, error)

VectorSearch 语义搜索。

type SegmentLayer 

type SegmentLayer int

SegmentLayer represents the layer of a segment. 

const (
	LayerL0 SegmentLayer = iota // Active (current window)
	LayerL1                     // Sealed hourly
	LayerL2                     // Compressed daily
	LayerL3                     // Archived weekly
)

func (SegmentLayer) String 

func (l SegmentLayer) String() string

type SegmentMeta 

type SegmentMeta struct {
	PartitionID int   `json:"pid"`
	WindowTS    int64 `json:"window_ts"`
	Layer       int   `json:"layer"` // 1=L1 (sealed), 2=L2, 3=L3
	EventCount  int   `json:"event_count"`
	MinTime     int64 `json:"min_time"`
	MaxTime     int64 `json:"max_time"`
	Sealed      bool  `json:"sealed"`
}

SegmentMeta holds metadata for a segment.

type StoreStats 

type StoreStats struct {
	TotalEvents int    `json:"total_events"`
	StorageSize int64  `json:"storage_size"`
	DataDir     string `json:"data_dir"`
}

StoreStats contains storage statistics.

type TombstoneSet 

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

TombstoneSet manages the set of tombstoned EventKeys.

func NewTombstoneSet 

func NewTombstoneSet(rel RelationStore, kv KVStore, pid int) *TombstoneSet

NewTombstoneSet creates a TombstoneSet.

func (*TombstoneSet) AllTombstones 

func (ts *TombstoneSet) AllTombstones() []int64

AllTombstones returns all tombstoned keys.

func (*TombstoneSet) Count 

func (ts *TombstoneSet) Count() int

Count returns the number of tombstoned keys.

func (*TombstoneSet) IsDirty 

func (ts *TombstoneSet) IsDirty() bool

IsDirty returns whether the tombstone set has unpersisted changes.

func (*TombstoneSet) IsTombstone 

func (ts *TombstoneSet) IsTombstone(key int64) bool

IsTombstone checks if an event key is tombstoned.

func (*TombstoneSet) LoadSnapshot 

func (ts *TombstoneSet) LoadSnapshot(data map[int64]bool) error

LoadSnapshot restores the tombstone set from a snapshot.

func (*TombstoneSet) MarkTombstone 

func (ts *TombstoneSet) MarkTombstone(key int64) error

MarkTombstone marks an event as tombstoned. Before marking, it triggers cascading parent repair for the event's children.

func (*TombstoneSet) MarshalJSON 

func (ts *TombstoneSet) MarshalJSON() ([]byte, error)

MarshalJSON serializes the tombstone set.

func (*TombstoneSet) RecoverFromKV 

func (ts *TombstoneSet) RecoverFromKV() error

RecoverFromKV restores tombstone state from KV store on startup.

func (*TombstoneSet) RemoveTombstones 

func (ts *TombstoneSet) RemoveTombstones(keys []int64) error

RemoveTombstones removes tombstone entries after compaction.

func (*TombstoneSet) Snapshot 

func (ts *TombstoneSet) Snapshot() (map[int64]bool, error)

Snapshot returns a serializable snapshot of the tombstone set.

func (*TombstoneSet) UnmarshalJSON 

func (ts *TombstoneSet) UnmarshalJSON(data []byte) error

UnmarshalJSON deserializes the tombstone set.

type TombstoneSnapshot 

type TombstoneSnapshot struct {
	Keys []int64 `json:"keys"`
}

TombstoneSnapshot is the JSON-serializable snapshot format.

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.