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 ¶
- type Action
- type CommitReference
- type ConversationDocument
- type ConversationIndexMetadata
- type ConversationParser
- type ConversationService
- type DecisionDocument
- type DocumentType
- type Extractor
- type FileReference
- type IndexOptions
- type IndexResult
- type MessageDocument
- type ParseAllResult
- type ParseError
- type ParseResult
- type Parser
- type RawMessage
- type Role
- type ScrubResult
- type Scrubber
- type SearchHit
- type SearchOptions
- type SearchResult
- type Service
- type ServiceConfig
- type ToolCall
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CommitReference ¶
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 (*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 ¶
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 (*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) 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 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.