memory

Documentation

Overview

Package memory manages project MEMORY.md and topic files under .pine/memory/.

Index

• Constants
• func AppendMEMORY(pineDir string, opts AppendOpts) error
• func AppendTopic(pineDir, slug string, opts AppendOpts) error
• func Confident(recs []Recommendation) bool
• func EnsureGlobalLayout() (string, error)
• func EnsureLayout(pineDir string) error
• func GlobalDir() (string, error)
• func GlobalLabel(dir string) string
• func MemoryPath(pineDir string) string
• func ReadMEMORY(pineDir string) (string, error)
• func ResolveTo(to string) (kind, value string, err error)
• func SetTopicLinks(pineDir, slug string, links []string) error
• func Slugify(s string) string
• func TopicPath(pineDir, slug string) string
• func TopicsDir(pineDir string) string
• func TruncateForContext(body string, capBytes int, srcLabel string) string
• type AppendOpts
• type Recommendation
  • func Suggest(pineDir string, opts SuggestOpts) ([]Recommendation, error)
• type SuggestOpts
• type Topic
  • func ListTopics(pineDir string) ([]Topic, error)
  • func ReadTopic(pineDir, slug string) (Topic, error)

Constants

const (
	// EnvHome relocates the machine-wide memory store. Unset/blank → ~/.pine.
	EnvHome = "PINE_HOME"
	// DirGlobal is the machine-wide store's directory name under the user's home.
	DirGlobal = ".pine"
	// ContextGlobalCap is the max bytes of the global MEMORY.md injected into
	// pine context. Deliberately smaller than ContextMEMORYCap: personal
	// preferences are a constitution, not a knowledge base.
	ContextGlobalCap = 2048
)

const (
	// FileMEMORY is the always-on project constitution under .pine/.
	FileMEMORY = "MEMORY.md"
	// DirTopics is the directory of append-only topic files under .pine/.
	DirTopics = "memory"

	// AutoMinScore is the minimum top recommendation score for auto-append.
	AutoMinScore = 0.55
	// AutoMinGap is the minimum score gap between #1 and #2 for auto-append.
	AutoMinGap = 0.12
	// SoftTopicThreshold below which we also suggest NEW:<slug>.
	SoftTopicThreshold = 0.4

	// ContextMEMORYCap is the max bytes of MEMORY.md injected into pine context.
	ContextMEMORYCap = 3500
)

const DefaultGlobalMEMORY = `` /* 389-byte string literal not displayed */

DefaultGlobalMEMORY is the seed written to ~/.pine/MEMORY.md on first use. It keeps the same H2 skeleton as DefaultMEMORY so AppendMEMORY's insertion into ## Log works against either store unchanged.

const DefaultMEMORY = `# Project memory

Stable preferences, conventions, and rules for this repository.
Agents: prefer appending here (or a topic under memory/) over creating new LRN-* files.
Ticket-scoped one-shots still use ` + "`pine learn --scope ticket`" + `.

## Preferences

## Conventions

## Gotchas

## Log
`

DefaultMEMORY is the seed content written by pine init / first append.

Functions

func AppendMEMORY

func AppendMEMORY(pineDir string, opts AppendOpts) error

AppendMEMORY appends a dated bullet under ## Log.

func AppendTopic

func AppendTopic(pineDir, slug string, opts AppendOpts) error

AppendTopic appends a bullet to memory/<slug>.md, creating the file if needed.

func Confident

func Confident(recs []Recommendation) bool

Confident reports whether the top recommendation may be auto-applied.

func EnsureGlobalLayout

func EnsureGlobalLayout() (string, error)

EnsureGlobalLayout resolves the machine-wide store and creates it with the personal seed on first use.

This is the only function that may create ~/.pine. Every read path leaves a missing global store missing: pine context must not conjure a store the user never opted into.

func EnsureLayout

func EnsureLayout(pineDir string) error

EnsureLayout creates memory/ and seeds the project MEMORY.md if missing.

func GlobalDir

func GlobalDir() (string, error)

GlobalDir resolves the machine-wide Pine home: $PINE_HOME when set, else <home>/.pine (%USERPROFILE%\.pine on Windows). It creates nothing.

func GlobalLabel

func GlobalLabel(dir string) string

GlobalLabel renders dir for humans: "~/.pine" at the default location, else dir itself — under $PINE_HOME a tilde path would name a file that does not exist.

func MemoryPath

func MemoryPath(pineDir string) string

PineDir helpers.

func ReadMEMORY

func ReadMEMORY(pineDir string) (string, error)

ReadMEMORY returns MEMORY.md contents (empty string if missing).

func ResolveTo

func ResolveTo(to string) (kind, value string, err error)

ResolveTo normalizes a --to argument into ("memory"|"topic"|"new", pathOrSlug).

func SetTopicLinks

func SetTopicLinks(pineDir, slug string, links []string) error

SetTopicLinks replaces the links frontmatter on a topic file, creating the file with a stub body when it does not yet exist.

func Slugify

func Slugify(s string) string

Slugify normalizes a topic name to a filename-safe slug.

func TopicPath

func TopicPath(pineDir, slug string) string

func TopicsDir

func TopicsDir(pineDir string) string

func TruncateForContext

func TruncateForContext(body string, capBytes int, srcLabel string) string

TruncateForContext returns a MEMORY body capped for pine context. srcLabel names the file to read in full and must match the store the body came from (".pine/MEMORY.md", "~/.pine/MEMORY.md", …) — a caller that gets this wrong points the reader at someone else's memory.

Types

type AppendOpts

type AppendOpts struct {
	Text  string
	Cites []string
	Now   time.Time
}

AppendOpts controls an append write.

type Recommendation

type Recommendation struct {
	Path   string  `json:"path"` // MEMORY.md | memory/<slug>.md | NEW:<slug>
	Score  float64 `json:"score"`
	Reason string  `json:"reason"`
}

Recommendation is a suggested destination for a new insight.

func Suggest

func Suggest(pineDir string, opts SuggestOpts) ([]Recommendation, error)

Suggest ranks MEMORY.md, existing topics, and optional NEW:<slug> destinations.

type SuggestOpts

type SuggestOpts struct {
	Text      string
	Cites     []string
	Component string
}

SuggestOpts controls destination ranking for a new insight.

type Topic

type Topic struct {
	Slug    string
	RelPath string // memory/<slug>.md
	Title   string
	Body    string
	Links   []string // typed graph refs (ticket / LRN-* / memory/<slug> / MEMORY)
	Updated time.Time
}

Topic is one .pine/memory/<slug>.md file.

func ListTopics

func ListTopics(pineDir string) ([]Topic, error)

ListTopics returns all topic files sorted by slug.

func ReadTopic

func ReadTopic(pineDir, slug string) (Topic, error)

ReadTopic loads one topic by slug.