neo4j

README

neo4j

Package neo4j is a history Store backed by Neo4j via the official Go driver (v5). Storage model: (:ChatMessage { conversation_id: "u-42", seq: , message: "", created_at: }) A composite index on (conversation_id, seq) is created by InitializeSchema=true so reads stream in insertion order without a full collection scan. A store-local sequence generator reserves one contiguous range per Write and remains monotonic across local clock regression. Concurrent calls and writes from distinct Store instances have no defined relative order. Example: drv, _ := neo4j.NewDriverWithContext("neo4j://...", auth) defer drv.Close(ctx) store, _ := neo4jstore.NewStore(ctx, neo4jstore.StoreConfig{ Driver: drv, Database: "neo4j", InitializeSchema: true, })

Install

go get github.com/Tangerg/scope/historystores/neo4j

Constructors

Every constructor validates its config and returns a value implementing the store capabilities in core/history:

• NewStore

Testing

This module integrates a third-party service, so its tests cover what runs without live credentials: config validation, request and response mapping, and error classification. The shared conformance contract is core/history/storetest — this module runs it rather than copying it.

An integration probe skips unless its credential environment variable is set, so go test ./... is always runnable offline.

Boundaries

This is an independent leaf module: it carries only its own SDK dependency and never imports a sibling provider. The shared contract every module in this family obeys is in ../ARCHITECTURE.md.

See ARCHITECTURE.md for what this module owns.

Documentation

Overview

Package neo4j is a history Store backed by Neo4j via the official Go driver (v5).

Storage model:

(:ChatMessage {
    conversation_id: "u-42",
    seq:             <int64 nanos>,
    message:         "<json>",
    created_at:      <datetime>
})

A composite index on (`conversation_id`, `seq`) is created by InitializeSchema=true so reads stream in insertion order without a full collection scan. A store-local sequence generator reserves one contiguous range per Write and remains monotonic across local clock regression. Concurrent calls and writes from distinct Store instances have no defined relative order.

Example:

drv, _ := neo4j.NewDriverWithContext("neo4j://...", auth)
defer drv.Close(ctx)
store, _ := neo4jstore.NewStore(ctx, neo4jstore.StoreConfig{
    Driver:           drv,
    Database:         "neo4j",
    InitializeSchema: true,
})

Index

• Constants
• type Store
  • func NewStore(ctx context.Context, config StoreConfig) (*Store, error)
  • func (s *Store) Clear(ctx context.Context, conversationID history.ConversationID) (err error)
  • func (s *Store) Conversations(ctx context.Context) (ids []history.ConversationID, err error)
  • func (s *Store) Read(ctx context.Context, conversationID history.ConversationID) (storedMessages []chat.Message, err error)
  • func (s *Store) Write(ctx context.Context, conversationID history.ConversationID, ...) (err error)
• type StoreConfig
  • func (s StoreConfig) Validate() error

Constants

const (
	DefaultDatabase = "neo4j"
	DefaultLabel    = "ChatMessage"
)

Types

type Store

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

Store persists messages as Neo4j nodes through a caller-owned driver. It validates dynamic labels before query construction and uses a local monotonic sequence for deterministic reads; ordering across separate Store values remains unspecified.

func NewStore

func NewStore(ctx context.Context, config StoreConfig) (*Store, error)

func (*Store) Clear

func (s *Store) Clear(ctx context.Context, conversationID history.ConversationID) (err error)

Clear deletes every node for conversationID under the configured label. Unknown ids are a no-op.

func (*Store) Conversations

func (s *Store) Conversations(ctx context.Context) (ids []history.ConversationID, err error)

Conversations returns every stored conversation ID in lexical order.

func (*Store) Read

func (s *Store) Read(ctx context.Context, conversationID history.ConversationID) (storedMessages []chat.Message, err error)

Read returns every message stored under conversationID in insertion order (seq ascending).

func (*Store) Write

func (s *Store) Write(ctx context.Context, conversationID history.ConversationID, messages ...chat.Message) (err error)

Write creates a new node per message under conversationID. A reserved sequence range preserves argument order and remains monotonic if the local clock moves backward.

type StoreConfig

type StoreConfig struct {
	// Driver is the live Neo4j driver. Required. Callers own its
	// lifetime.
	Driver neo4j.DriverWithContext

	// Database selects the Neo4j database to operate against.
	// Optional: defaults to [DefaultDatabase] ("neo4j").
	Database string

	// Label is the node label used for stored messages. Optional:
	// defaults to [DefaultLabel] ("ChatMessage").
	Label string

	// InitializeSchema, when true, creates an index on
	// (conversation_id, seq) for the chosen label. Idempotent.
	InitializeSchema bool
}

func (StoreConfig) Validate

func (s StoreConfig) Validate() error