memory

package
v0.36.0 Latest Latest
Warning

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

 Go to latest Published: Oct 17, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package memory provides deliberate, scoped context for PitCrew agents.

Package memory stores local, project-aware context for registered agents. It is separate from shared project knowledge pages.

Index

Constants

View Source 
const (
	DefaultOwner     = "codex"
	DefaultAgent     = "codex"
	MaxContentBytes  = 1 << 20
	MaxTitleBytes    = 512
	MaxTopicBytes    = 256
	MaxSearchLimit   = 100
	DefaultSearchMax = 20
)
View Source 
const MaxEngramDiagnostics = 100
View Source 
const MaxEngramExportBytes = 64 << 20
View Source 
const SkillName = "pitcrew-memory"
View Source 
const SkillVersion = "1.3.0"

Variables

View Source 
var (
	ErrProjectNotFound    = errors.New("memory project not found")
	ErrProjectArchived    = errors.New("memory project is archived")
	ErrNotFound           = errors.New("memory record not found")
	ErrSessionNotFound    = errors.New("registered runtime session not found")
	ErrSessionConflict    = errors.New("runtime session identity conflicts with its registered checkout")
	ErrNoActiveSession    = errors.New("no active registered runtime session for this checkout")
	ErrAmbiguousSession   = errors.New("multiple active runtime sessions exist for this checkout; memory writes are disabled")
	ErrInvalidInput       = errors.New("invalid memory input")
	ErrRevisionConflict   = errors.New("memory changed; read the latest revision and reconcile the edit")
	ErrRepositoryNotReady = errors.New("checkout is not associated with an active PitCrew project")
)

Functions

func RedactPrompt 

func RedactPrompt(value string) string

RedactPrompt removes common credential forms before an explicitly enabled prompt capture. It does not inspect or read a conversation transcript.

func Serve 

func Serve(ctx context.Context, in io.Reader, out io.Writer, store *Store, repositoryRoot string) error

Serve remains the memory-only transport entry point for package callers.

func SkillFiles 

func SkillFiles() map[string][]byte

SkillFiles returns a fresh copy of the installable, product-owned memory skill package.

Types

type EngramArchivedSession added in v0.36.0 

type EngramArchivedSession struct {
	ID         int64                    `json:"id"`
	Project    string                   `json:"project"`
	OwnerID    string                   `json:"ownerId"`
	SourceKey  string                   `json:"sourceKey"`
	Historical bool                     `json:"historical"`
	CreatedAt  string                   `json:"createdAt"`
	Provenance *EngramSessionProvenance `json:"engramSource,omitempty"`
}

type EngramDiagnostic added in v0.36.0 

type EngramDiagnostic struct {
	Code    string `json:"code"`
	Label   string `json:"label"`
	Message string `json:"message"`
}

type EngramImportItem added in v0.35.0 

type EngramImportItem struct {
	SourceKey string `json:"sourceKey"`
	Scope     string `json:"scope"`
	MemoryID  int64  `json:"memoryId,omitempty"`
	Type      string `json:"type"`
	Status    string `json:"status"`
}

type EngramImportParams added in v0.35.0 

type EngramImportParams struct {
	Project, SourceProject, SourceID, OwnerID, Actor string
	Apply, IncludePersonal                           bool
}

type EngramImportResult added in v0.35.0 

type EngramImportResult struct {
	Project              string              `json:"project"`
	SourceProject        string              `json:"sourceProject"`
	Apply                bool                `json:"apply"`
	Applied              bool                `json:"applied"`
	Selected             int                 `json:"selected"`
	ProjectObservations  int                 `json:"projectObservations"`
	PersonalObservations int                 `json:"personalObservations"`
	IncludePersonal      bool                `json:"includePersonal"`
	Ignored              int                 `json:"ignoredOtherProjects"`
	Sessions             int                 `json:"historicalSessions"`
	StandaloneSessions   int                 `json:"standaloneSessions"`
	Items                []EngramImportItem  `json:"items"`
	SessionItems         []EngramSessionItem `json:"sessionItems"`
	Blockers             int                 `json:"blockers"`
	Diagnostics          []EngramDiagnostic  `json:"diagnostics"`
	DiagnosticsTruncated bool                `json:"diagnosticsTruncated"`
	Types                map[string]int      `json:"sourceTypes"`
	Scopes               map[string]int      `json:"sourceScopes"`
}

type EngramProvenance added in v0.35.0 

type EngramProvenance struct {
	Source         string          `json:"source"`
	SourceID       string          `json:"sourceId"`
	SourceProject  string          `json:"sourceProject"`
	SourceKey      string          `json:"sourceKey"`
	Historical     bool            `json:"historical"`
	Observation    json.RawMessage `json:"observation"`
	Session        json.RawMessage `json:"session,omitempty"`
	ExportMetadata json.RawMessage `json:"exportMetadata"`
}

EngramProvenance is historical, untrusted source data, never runtime identity.

type EngramSessionItem added in v0.36.0 

type EngramSessionItem struct {
	ID        int64  `json:"id,omitempty"`
	SourceKey string `json:"sourceKey"`
	Status    string `json:"status"`
}

type EngramSessionProvenance added in v0.36.0 

type EngramSessionProvenance struct {
	Source         string          `json:"source"`
	SourceID       string          `json:"sourceId"`
	SourceProject  string          `json:"sourceProject"`
	SourceKey      string          `json:"sourceKey"`
	Historical     bool            `json:"historical"`
	Session        json.RawMessage `json:"session"`
	ExportMetadata json.RawMessage `json:"exportMetadata"`
}

EngramSessionProvenance is an archived source record, never a live session.

type MCPHandler 

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

func NewHostMCPHandler added in v0.34.0 

func NewHostMCPHandler(store *Store, repositoryRoot, host string) (*MCPHandler, error)

NewHostMCPHandler binds the server to the host agent without inferring a session.

func NewMCPHandler 

func NewMCPHandler(store *Store, repositoryRoot string) (*MCPHandler, error)

func (*MCPHandler) CallTool 

func (h *MCPHandler) CallTool(ctx context.Context, name string, arguments map[string]any) (any, error)

func (*MCPHandler) Tools 

func (h *MCPHandler) Tools() []mcpserver.Tool

type Record 

type Record struct {
	Historical       bool              `json:"historical,omitempty"`
	EngramSource     *EngramProvenance `json:"engramSource,omitempty"`
	ID               int64             `json:"id"`
	Scope            string            `json:"scope"`
	ProjectID        *int64            `json:"projectId,omitempty"`
	ProjectKey       string            `json:"projectKey,omitempty"`
	OwnerID          string            `json:"ownerId"`
	Type             string            `json:"type"`
	Title            string            `json:"title"`
	Content          string            `json:"content,omitempty"`
	Topic            string            `json:"topic,omitempty"`
	AgentID          string            `json:"agentId,omitempty"`
	SessionID        string            `json:"sessionId,omitempty"`
	Revision         int               `json:"revision"`
	CreatedAt        time.Time         `json:"createdAt"`
	UpdatedAt        time.Time         `json:"updatedAt"`
	DeletedAt        *time.Time        `json:"deletedAt,omitempty"`
	Snippet          string            `json:"snippet,omitempty"`
	MatchedFields    []string          `json:"matchedFields,omitempty"`
	ContentTruncated bool              `json:"contentTruncated,omitempty"`
	// contains filtered or unexported fields
}

Record is one current memory item. Content is omitted by metadata-only reads.

type SaveParams 

type SaveParams struct {
	Project, Scope, OwnerID, Type, Title, Content, Topic string
	AgentID, SessionID, Actor                            string
}

type SearchParams 

type SearchParams struct {
	Project, OwnerID, Query string
	Limit                   int
	CrossProjectFallback    bool
	// contains filtered or unexported fields
}

type SearchResults 

type SearchResults struct {
	Query                string   `json:"query"`
	Results              []Record `json:"results"`
	Total                int      `json:"total"`
	Limit                int      `json:"limit"`
	Truncated            bool     `json:"truncated"`
	CrossProjectFallback bool     `json:"crossProjectFallback"`
}

type Session 

type Session struct {
	ID        string     `json:"sessionId"`
	ProjectID int64      `json:"projectId"`
	Project   string     `json:"projectKey"`
	RepoRoot  string     `json:"repositoryRoot"`
	AgentID   string     `json:"agentId"`
	StartedAt time.Time  `json:"startedAt"`
	LastSeen  time.Time  `json:"lastSeenAt"`
	EndedAt   *time.Time `json:"endedAt,omitempty"`
}

type Store 

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

Store owns memory records and runtime session registration in the shared DB.

func Open 

func Open(ctx context.Context, path string) (*Store, error)

func OpenReadOnly 

func OpenReadOnly(ctx context.Context, path string) (*Store, error)

func (*Store) CapturePrompt 

func (s *Store) CapturePrompt(ctx context.Context, cwd, sessionID, redactedPrompt string) (Record, error)

CapturePrompt records one already-redacted prompt only after explicit opt-in.

func (*Store) Close 

func (s *Store) Close() error

func (*Store) Context 

func (s *Store) Context(ctx context.Context, projectName, owner string, limit int) ([]Record, error)

Context returns a small recent set for session startup or post-compaction.

func (*Store) CrossProjectRecallEnabled added in v0.33.0 

func (s *Store) CrossProjectRecallEnabled(ctx context.Context, owner string) (bool, error)

CrossProjectRecallEnabled fails closed: an agent without an explicit durable preference retains project isolation. This preference is not session identity.

func (*Store) CurrentSession 

func (s *Store) CurrentSession(ctx context.Context, cwd string) (Session, error)

func (*Store) Delete 

func (s *Store) Delete(ctx context.Context, id int64, expectedRevision int, hard bool, who string) error

Delete soft-deletes by default. Hard deletion removes content after recording a metadata-only audit event; audit history never stores memory text.

func (*Store) DeleteEngramSession added in v0.36.0 

func (s *Store) DeleteEngramSession(ctx context.Context, projectName, owner string, id int64) error

DeleteEngramSession erases raw session/export data, retaining a conflict tombstone.

func (*Store) EndSession 

func (s *Store) EndSession(ctx context.Context, sessionID, cwd string) error

func (*Store) EngramSessions added in v0.36.0 

func (s *Store) EngramSessions(ctx context.Context, projectName, owner string, id, after int64, limit int) ([]EngramArchivedSession, error)

EngramSessions lists metadata in one explicitly selected project and owner. Raw source/session IDs appear only in the explicitly requested full read.

func (*Store) EngramSource added in v0.35.0 

func (s *Store) EngramSource(ctx context.Context, id int64) (*EngramProvenance, error)

EngramSource returns preserved provenance, including unknown source fields.

func (*Store) Get 

func (s *Store) Get(ctx context.Context, id int64) (Record, error)

func (*Store) GetForContext 

func (s *Store) GetForContext(ctx context.Context, id int64, projectName, owner string) (Record, error)

GetForContext limits agent reads to its current project and personal scope.

func (*Store) GetForRecall added in v0.33.0 

func (s *Store) GetForRecall(ctx context.Context, id int64, projectName, owner string) (Record, error)

GetForRecall permits read-only retrieval from other active registered projects. Mutations still use GetForContext and therefore cannot modify fallback records.

func (*Store) ImportEngram added in v0.35.0 

func (s *Store) ImportEngram(ctx context.Context, input io.Reader, p EngramImportParams) (EngramImportResult, error)

ImportEngram previews or atomically applies one explicitly mapped project. Personal source observations require explicit consent and retain owner-only scope.

func (*Store) List 

func (s *Store) List(ctx context.Context, projectName, owner string, limit int) ([]Record, error)

List returns bounded metadata in one project plus the agent's personal scope.

func (*Store) ListSessions 

func (s *Store) ListSessions(ctx context.Context, cwd string) ([]Session, error)

func (*Store) PromptCaptureEnabled 

func (s *Store) PromptCaptureEnabled(ctx context.Context) (bool, error)

func (*Store) RegisterSession 

func (s *Store) RegisterSession(ctx context.Context, sessionID, cwd, agentID string) (Session, error)

func (*Store) Save 

func (s *Store) Save(ctx context.Context, params SaveParams) (Record, error)

Save creates a record or updates the active record with the same scoped topic. Session attribution is validated against a session registered by the host hook.

func (*Store) Search 

func (s *Store) Search(ctx context.Context, params SearchParams) (SearchResults, error)

func (*Store) SessionForHost added in v0.34.0 

func (s *Store) SessionForHost(ctx context.Context, id, root, host string) (Session, error)

SessionForHost validates exact session, checkout registration and host identity.

func (*Store) SessionScopeActive added in v0.34.0 

func (s *Store) SessionScopeActive(ctx context.Context, root string) (bool, error)

SessionScopeActive distinguishes absent/inactive registrations from store errors.

func (*Store) SetCrossProjectRecall added in v0.33.0 

func (s *Store) SetCrossProjectRecall(ctx context.Context, owner, policy, who string) error

func (*Store) SetPromptCapture 

func (s *Store) SetPromptCapture(ctx context.Context, enabled bool, who string) error

SetPromptCapture stores only the explicit preference; it is disabled on fresh installs.

func (*Store) SummarizeSession 

func (s *Store) SummarizeSession(ctx context.Context, cwd, sessionID, summary, who string) (Record, error)

func (*Store) Update 

func (s *Store) Update(ctx context.Context, p UpdateParams) (Record, error)

Update replaces user-managed fields only after an optimistic revision check.

type UpdateParams 

type UpdateParams struct {
	ID                          int64
	ExpectedRevision            int
	Type, Title, Content, Topic string
	Actor                       string
}

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.