conversation

package
v0.3.4 Latest Latest
Warning

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

Go to latest
Published: Jan 14, 2026 License: GPL-3.0 Imports: 15 Imported by: 0

Documentation

Overview

Package conversation provides indexing and search capabilities for Claude Code conversation files (JSONL format).

The package supports:

  • Parsing Claude Code conversation files from ~/.claude/projects/
  • Extracting file references and git commit metadata from messages
  • Indexing conversations into a vector store for semantic search
  • Searching indexed conversations with filters for type, tags, files, and domains

Architecture

The main components are:

  • Parser: Reads JSONL conversation files and extracts messages
  • Extractor: Extracts file references and commit metadata from messages
  • Service: Coordinates indexing and search operations

Usage

Create a service with a vector store and optional secret scrubber:

svc := conversation.NewService(
    vectorStore,
    secretScrubber,
    logger,
    conversation.ServiceConfig{
        ConversationsPath: "/path/to/conversations",
    },
)

Index conversations for a project:

result, err := svc.Index(ctx, conversation.IndexOptions{
    ProjectPath: "/path/to/project",
    TenantID:    "my-tenant",
})

Search indexed conversations:

result, err := svc.Search(ctx, conversation.SearchOptions{
    Query:       "authentication flow",
    ProjectPath: "/path/to/project",
    TenantID:    "my-tenant",
    Limit:       10,
})

Multi-Tenancy

The service uses payload-based tenant isolation. All indexed documents are tagged with tenant metadata and queries are automatically filtered by tenant. Collection names are sanitized to ensure safe storage, with SHA-256 hash fallback for non-ASCII tenant/project names.

Secret Scrubbing

If a Scrubber is provided, all message content is scrubbed before indexing and before returning search results. This prevents accidental storage or exposure of secrets like API keys or tokens.

Package conversation provides functionality for indexing and searching past Claude Code sessions. It parses JSONL conversation files, extracts messages and decisions, and stores them in a vector database for semantic search.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Action

type Action string

Action represents the type of file operation.

const (
	ActionRead    Action = "read"
	ActionEdited  Action = "edited"
	ActionCreated Action = "created"
	ActionDeleted Action = "deleted"
)

type CommitReference

type CommitReference struct {
	SHA     string `json:"sha"`
	Message string `json:"message,omitempty"`
}

CommitReference represents a git commit linked to a conversation.

type ConversationDocument

type ConversationDocument struct {
	// Identity
	ID        string       `json:"id"`
	SessionID string       `json:"session_id"`
	Type      DocumentType `json:"type"`
	Timestamp time.Time    `json:"timestamp"`

	// Content (embedded for search)
	Content string `json:"content"`

	// Context tags
	Tags   []string `json:"tags,omitempty"`
	Domain string   `json:"domain,omitempty"`

	// Cross-references
	FilesDiscussed []FileReference   `json:"files_discussed,omitempty"`
	CommitsMade    []CommitReference `json:"commits_made,omitempty"`

	// Metadata
	IndexedAt        time.Time `json:"indexed_at"`
	ExtractionMethod string    `json:"extraction_method"`
}

ConversationDocument is the base document type stored in the vector database.

type ConversationIndexMetadata

type ConversationIndexMetadata struct {
	ProjectPath       string    `json:"project_path"`
	TenantID          string    `json:"tenant_id"`
	LastIndexedAt     time.Time `json:"last_indexed_at"`
	SessionsIndexed   int       `json:"sessions_indexed"`
	MessagesIndexed   int       `json:"messages_indexed"`
	DecisionsIndexed  int       `json:"decisions_indexed"`
	IndexedSessionIDs []string  `json:"indexed_session_ids"`
}

ConversationIndexMetadata tracks the indexing state for a project.

type ConversationParser

type ConversationParser interface {
	// Parse reads a JSONL file and extracts messages.
	Parse(path string) ([]RawMessage, error)

	// ParseAll reads all JSONL files in a directory.
	ParseAll(dir string) (map[string][]RawMessage, error)
}

ConversationParser defines the interface for parsing conversation files.

type ConversationService

type ConversationService interface {
	// Index processes and stores conversations for a project.
	Index(ctx context.Context, opts IndexOptions) (*IndexResult, error)

	// Search finds relevant conversations.
	Search(ctx context.Context, opts SearchOptions) (*SearchResult, error)
}

ConversationService defines the interface for conversation operations.

type DecisionDocument

type DecisionDocument struct {
	ConversationDocument

	// Decision-specific fields
	Summary           string   `json:"summary"`
	Alternatives      []string `json:"alternatives,omitempty"`
	Reasoning         string   `json:"reasoning,omitempty"`
	Confidence        float64  `json:"confidence"`
	SourceMessageUUID string   `json:"source_message_uuid"`
}

DecisionDocument represents an extracted decision from a conversation.

type DocumentType

type DocumentType string

DocumentType represents the type of conversation document.

const (
	// TypeMessage is an individual user or assistant message.
	TypeMessage DocumentType = "message"
	// TypeDecision is an extracted decision from conversation.
	TypeDecision DocumentType = "decision"
	// TypeSummary is a session summary (future enhancement).
	TypeSummary DocumentType = "summary"
)

type Extractor

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

Extractor extracts file references, commit SHAs, and other metadata from messages.

func NewExtractor

func NewExtractor() *Extractor

NewExtractor creates a new metadata extractor.

func (*Extractor) ExtractCommitReferences

func (e *Extractor) ExtractCommitReferences(msg RawMessage) []CommitReference

ExtractCommitReferences extracts git commit SHAs from messages.

func (*Extractor) ExtractFileReferences

func (e *Extractor) ExtractFileReferences(msg RawMessage) []FileReference

ExtractFileReferences extracts file references from tool calls in a message.

func (*Extractor) ExtractMetadata

func (e *Extractor) ExtractMetadata(msg RawMessage) (files []FileReference, commits []CommitReference)

ExtractMetadata extracts all metadata from a message.

type FileReference

type FileReference struct {
	Path       string   `json:"path"`
	LineRanges []string `json:"line_ranges,omitempty"`
	Action     Action   `json:"action"`
}

FileReference represents a file discussed in a conversation.

type IndexOptions

type IndexOptions struct {
	ProjectPath string   `json:"project_path"`
	TenantID    string   `json:"tenant_id"`
	SessionIDs  []string `json:"session_ids,omitempty"` // Empty = all sessions
	EnableLLM   bool     `json:"enable_llm"`
	Force       bool     `json:"force"` // Reindex existing
}

IndexOptions configures how conversations are indexed.

type IndexResult

type IndexResult struct {
	SessionsIndexed    int      `json:"sessions_indexed"`
	MessagesIndexed    int      `json:"messages_indexed"`
	DecisionsExtracted int      `json:"decisions_extracted"`
	FilesReferenced    []string `json:"files_referenced"`
	Errors             []error  `json:"errors,omitempty"`
}

IndexResult contains the results of an indexing operation.

type MessageDocument

type MessageDocument struct {
	ConversationDocument

	// Message-specific fields
	Role         Role   `json:"role"`
	MessageUUID  string `json:"message_uuid"`
	MessageIndex int    `json:"message_index"`
}

MessageDocument represents an individual message from a conversation.

type ParseAllResult

type ParseAllResult struct {
	Messages   map[string][]RawMessage
	Errors     []ParseError
	ErrorCount int
}

ParseAll reads all JSONL files in a directory and returns messages grouped by session. ParseAllResult holds results from ParseAll including errors.

type ParseError

type ParseError struct {
	Line  int
	Error string
}

ParseError represents a parsing error at a specific line.

type ParseResult

type ParseResult struct {
	Messages   []RawMessage
	ErrorCount int
	Errors     []ParseError
}

ParseResult contains messages and any errors encountered during parsing.

type Parser

type Parser struct{}

Parser implements ConversationParser for Claude Code JSONL files.

func NewParser

func NewParser() *Parser

NewParser creates a new conversation parser.

func (*Parser) Parse

func (p *Parser) Parse(path string) ([]RawMessage, error)

Parse reads a JSONL file and extracts messages. Returns partial results on parse errors rather than failing completely.

func (*Parser) ParseAll

func (p *Parser) ParseAll(dir string) (map[string][]RawMessage, error)

func (*Parser) ParseAllWithErrors

func (p *Parser) ParseAllWithErrors(dir string) (*ParseAllResult, error)

ParseAllWithErrors parses all JSONL files and returns results with error details.

func (*Parser) ParseWithErrors

func (p *Parser) ParseWithErrors(path string) (*ParseResult, error)

ParseWithErrors reads a JSONL file and returns messages along with any parse errors.

type RawMessage

type RawMessage struct {
	SessionID  string     `json:"session_id"`
	UUID       string     `json:"uuid"`
	Timestamp  time.Time  `json:"timestamp"`
	Role       Role       `json:"role"`
	Content    string     `json:"content"`
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
	GitBranch  string     `json:"git_branch,omitempty"`
	ParentUUID string     `json:"parent_uuid,omitempty"`
}

RawMessage represents a parsed message from a Claude Code JSONL file.

type Role

type Role string

Role represents the role of a message sender.

const (
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
)

type ScrubResult

type ScrubResult interface {
	GetScrubbed() string
}

ScrubResult holds the result of secret scrubbing.

type Scrubber

type Scrubber interface {
	Scrub(content string) ScrubResult
}

Scrubber is an interface for secret scrubbing.

type SearchHit

type SearchHit struct {
	Document ConversationDocument `json:"document"`
	Score    float64              `json:"score"`
}

SearchHit represents a single search result.

type SearchOptions

type SearchOptions struct {
	Query       string         `json:"query"`
	ProjectPath string         `json:"project_path"`
	TenantID    string         `json:"tenant_id"`
	Types       []DocumentType `json:"types,omitempty"` // TypeMessage, TypeDecision, TypeSummary
	Tags        []string       `json:"tags,omitempty"`
	FilePath    string         `json:"file_path,omitempty"`
	Domain      string         `json:"domain,omitempty"`
	Limit       int            `json:"limit"`
}

SearchOptions configures how conversations are searched.

type SearchResult

type SearchResult struct {
	Query   string        `json:"query"`
	Results []SearchHit   `json:"results"`
	Total   int           `json:"total"`
	Took    time.Duration `json:"took"`
}

SearchResult contains the results of a search operation.

type Service

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

Service implements ConversationService for indexing and searching conversations.

func NewService

func NewService(
	store vectorstore.Store,
	scrubber Scrubber,
	logger *zap.Logger,
	cfg ServiceConfig,
) *Service

NewService creates a new conversation service.

func (*Service) Index

func (s *Service) Index(ctx context.Context, opts IndexOptions) (*IndexResult, error)

Index processes and stores conversations for a project.

func (*Service) Search

func (s *Service) Search(ctx context.Context, opts SearchOptions) (*SearchResult, error)

Search finds relevant conversations.

type ServiceConfig

type ServiceConfig struct {
	ConversationsPath string // Base path for conversation files
}

ServiceConfig holds configuration for the conversation service.

type ToolCall

type ToolCall struct {
	Name   string            `json:"name"`
	Params map[string]string `json:"params,omitempty"`
	Result string            `json:"result,omitempty"`
}

ToolCall represents a tool invocation within a message.

Jump to

Keyboard shortcuts

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