memory

Documentation

Overview

Package memory reads what the agent noted for itself in a previous session.

Reading only, and reading a file a person can edit by hand — that is the whole design. The memory lives in the user's repository and is reviewed in a diff, because a wrong memory does not sit still: the agent reads its own mistake back as fact and acts on it with more confidence than the first time.

Index

• Constants
• func Path(workspace string) string
• func Render(f File, max int, known map[string]bool) string
• type Entry
• type File
  • func Read(workspace string) (File, error)
• type Kind
  • func Kinds() []Kind
  • func (k Kind) Valid() bool

Constants

const DefaultMax = 40

DefaultMax is how many memories reach the prefix.

A starting value with no observation behind it, and saying so is the point: a ceiling has to exist before there is use, or the first session that writes too much eats the window and nobody finds out why. What to do with it is measure and move it, with a changelog saying what was seen. Fixing a ceiling by reasoning and never revisiting it is the mistake EVAL_TIMEOUT made twice.

const FileName = ".dcode/memory.md"

FileName is where a workspace keeps what was learned in it.

Not configurable, and the absence of a key is the decision: a configurable path is a memory one machine reads and another does not, for the same check on the same repository.

Functions

func Path

func Path(workspace string) string

Path is where the memory of this workspace lives.

func Render

func Render(f File, max int, known map[string]bool) string

Render turns what was learned into the block the prefix carries, or "" when there is nothing to say.

known is the set of commits the repository still has; a memory whose commit is not in it is MARKED, never dropped. The heuristic will be wrong sometimes, and a wrong heuristic that deletes is knowledge lost with nobody told. An empty set means nothing could be checked, and then nothing is marked — "we did not look" must not read as "we looked and it is gone".

Types

type Entry

type Entry struct {
	Kind    Kind
	Subject string
	// Learned and Commit are what make staleness checkable rather than guessed
	// at. Either may be empty in a file somebody wrote by hand, and that is
	// allowed: a memory with no provenance is still a memory.
	Learned string
	Commit  string
	Body    string
}

Entry is one thing that was learned.

type File

type File struct {
	Entries []Entry
	// Malformed names the lines that looked like a memory and were not. Reported
	// rather than swallowed: a session must not fail over a crooked block, and a
	// block silently dropped is knowledge lost with nobody told.
	Malformed []string
}

File is what a workspace remembers, and what could not be read.

func Read

func Read(workspace string) (File, error)

Read parses the memory of a workspace.

A missing file is the ordinary case and is silent: a workspace that never learned anything is every workspace on its first day, and nothing new may fail because there is nothing to read.

type Kind

type Kind string

Kind is what a memory is. The list is closed: memory without a kind becomes a diary, and a diary becomes noise in two weeks.

const (
	// KindGotcha cost time and will cost it again.
	KindGotcha Kind = "gotcha"
	// KindDecision is a choice and its reason, so it is not relitigated.
	KindDecision Kind = "decision"
	// KindConvention is how this repository does something, discovered rather
	// than documented.
	KindConvention Kind = "convention"
)

func Kinds

func Kinds() []Kind

Kinds is the closed list, in the order the spec names them.

func (Kind) Valid

func (k Kind) Valid() bool

Valid reports whether k is one of the three.