Documentation
¶
Overview ¶
Package ops is each operation once, for every surface. The CLI, the MCP server and the hooks used to each call the memory package and compose their own report of what happened, and the reports drifted: #241 was the review queue's hand-edit announcement fixed for one surface while another said nothing, and a remember whose vault write failed lost its memory id on both. An operation here returns what it found plus an Outcome — what it did on the way, with counts, and what failed — and a surface only renders it.
Index ¶
- Constants
- func Anchor(m *memory.Memory, dir string)
- func AutoAcceptedSinceReview(db *sql.DB) (int, error)
- func AutoLead(vault, project string) string
- func AutoReview(db *sql.DB, vault string, now time.Time) (int, error)
- func Backticked(c string) string
- func NotDurable(stranded bool) string
- func Plain(c string) string
- func ProjectExists(db *sql.DB, vault, name string) bool
- func PromotionReceipt(p Promotion) string
- func QueueAdoption(restored, rejected int) string
- func QueueLine(waiting, autoAccepted int, shell string, cmd func(string) string) string
- func RecallIDs(db *sql.DB, ids []string, here, dir string) (string, error)
- func RunAutoReview(db *sql.DB, vault, project string) string
- func TurnRef(harness, path string, turns int) string
- type Block
- type CorrectRequest
- type CorrectResult
- type Note
- type Omitted
- type Outcome
- type Promotion
- type RecallQuery
- type RecallResult
- type Recalled
- type RememberRequest
- type RememberResult
- type Searched
- type Window
Constants ¶
const ( StatusOK = "ok" StatusEmpty = "empty" StatusPartial = "partial" StatusFailed = "failed" )
const DecisionHolds = 3
DecisionHolds is how many checkpoints have to record a decision before it is proposed as project memory. Once is a choice; agents copying it forward into a third checkpoint is the project treating it as settled.
Variables ¶
This section is empty.
Functions ¶
func Anchor ¶ added in v0.5.3
Anchor records where the repository at dir stood when m was written, unless m already carries a commit (an import, or a caller that knows better). It also resolves the repo's remote into m.Remote, the one-time input to the memory's uid (see Memory.Uid) — a separate guard from Commit's, so a caller that already set one does not suppress the other.
func AutoAcceptedSinceReview ¶
AutoAcceptedSinceReview is how many memories the review switch accepted since a person last accepted or rejected one: the number every mention of the queue carries, so what was accepted for the user is never out of their sight.
func AutoLead ¶
AutoLead is what resume does about auto, as the lines that open it, the same on the CLI and over MCP, or "" when there is nothing to say: AutoReport, then the day's dream if it is due. The report comes first so it covers the last dream, not the one just launched.
func AutoReview ¶
AutoReview runs the review switch over the queue and returns how many it accepted. Off, it does nothing at all. A memory it could not accept is reported, and the rest are still tried: one failure is not a reason to leave the others for a person who turned the switch on to be spared them.
func Backticked ¶
Backticked is how an agent's markdown shows a command; Plain is a terminal.
func NotDurable ¶
NotDurable is worded as a fact about where a memory is rather than a warning, because the memory itself is fine — an agent should still use it, and should know not to rely on it being there tomorrow.
func ProjectExists ¶
ProjectExists reports whether the vault has ever heard this exact name — either a memory filed under it or a session directory carrying it. Both are consulted because a project can have checkpoints and no memory, or memory and no checkpoint, and either one makes the name real.
func PromotionReceipt ¶ added in v0.5.5
PromotionReceipt is the line a checkpoint adds when the pass did something, "" when it did nothing.
func QueueAdoption ¶
QueueAdoption says what a hand edit to the review queue file did to the queue, in the words `logos review` prints for the same adoption. Empty when nothing changed, which is nearly always.
func QueueLine ¶
QueueLine is the review queue in one line: what waits for the user, and what the review switch accepted for them since they last looked. Empty when there is neither. cmd wraps a command as the reader shows it: backticks for an agent's markdown, nothing for a terminal.
func RecallIDs ¶ added in v0.5.3
RecallIDs serves memories by the ids a compact recall (or list_memories) printed. here is the project the asker stands in, for labelling another project's memory as such, and dir the repository it stands in, for the same drift mark a search gives. Every id gets a line: one that is gone, replaced, waiting for review or excluded says which, because an id that silently returns nothing reads as a memory that never existed.
func RunAutoReview ¶
RunAutoReview is the sweep as resume runs it: logged, so the auto line resume opens with says what it accepted, and a failure returned as a line to print, since resume has nobody to return an error to but the reader.
Types ¶
type Block ¶ added in v0.5.5
type Block struct {
Status string `json:"status"`
Searched []Searched `json:"searched"`
Returned int `json:"returned"`
Omitted Omitted `json:"omitted"`
Window *Window `json:"window,omitempty"`
Errors []string `json:"errors"`
// Notes is what the text answer would have said beside the result — the
// review queue's count, a sweep that saved a missing checkpoint. Kept,
// because a feature that announces itself in text and goes quiet in JSON
// is a feature the agents reading JSON never hear about.
Notes []string `json:"notes,omitempty"`
}
Block is the outcome block every --json answer carries (amp-spec §9.5): what was searched, how much came back, what was held back and why, and what went wrong. It exists because a JSON consumer cannot read the prose a text answer puts around its result, and the one reading that prose prevented — "nothing found" from "could not look" — is the one a list alone cannot make. An empty array is both.
func (*Block) Absorb ¶ added in v0.5.5
Absorb moves an Outcome's notes into the block: a failed note is an error, the rest are notes.
func (*Block) Settle ¶ added in v0.5.5
func (b *Block) Settle()
Settle fills Status from the rest of the block. Anything that went wrong makes it partial rather than failed, because a block that is being settled had a result to report — failed is only for an answer that never got one, and Failure builds that. Held back for budget is partial too: the reader was told less than matched and has to know to ask with more room.
type CorrectRequest ¶ added in v0.5.3
type CorrectRequest struct {
ID int64
Memory memory.Memory // the text that is true now; kind and project come from ID
Embed *provider.Provider
Model string
// DirFor names the repository a project lives in, or "". The correction
// is anchored where the project of the memory it replaces stands — not
// where the caller does, which may be a different project's checkout.
DirFor func(project string) string
}
type CorrectResult ¶ added in v0.5.3
type CorrectResult struct {
Correction memory.Correction `json:"correction"`
Outcome Outcome `json:"outcome"`
}
func Correct ¶ added in v0.5.3
func Correct(db *sql.DB, req CorrectRequest) (CorrectResult, error)
Correct replaces a memory with what is true now. As with Remember, the error is for a correction refused before anything changed; one the cache made and the vault did not is a result with the failure in its Outcome, because the new id is the handle anyone needs to retry it.
type Note ¶
Note is one thing an operation has to say beyond its result. Ordered, not keyed, because the order is part of the report: the adoption of a hand edit reads before the count it changed.
type Omitted ¶ added in v0.5.5
type Omitted struct {
Budget int `json:"budget"`
Scope int `json:"scope"`
Quarantined int `json:"quarantined"`
Stale int `json:"stale"`
AnchorUnknown int `json:"anchor_unknown"`
}
Omitted counts what matched and was not returned, by reason. Every key is always present, as the spec writes them, so a reader can sum them without first asking which ones this command knows about; a zero is "none held back for that reason here".
type Outcome ¶
type Outcome struct {
Notes []Note `json:"notes,omitempty"`
}
Outcome is what an operation did besides answering, and what went wrong. A failure that does not void the result — the review queue could not be counted, the vault refused a write the cache took — is a failed note rather than an error, so the half that succeeded is still reported (invariant 4).
func AutoReport ¶
AutoReport is what resume says about auto: what it did out of sight since the project's last checkpoint an agent wrote, and anything wrong with auto.md. Since that checkpoint and not since the last one of any kind, because the latest is often the one auto wrote at session end, and the report is there to say it was auto that wrote it.
func ReviewQueue ¶
ReviewQueue is what every read reports while the review queue is not empty. Quarantine keeps an agent's memories out of recall until the user says yes, and a user who is never told there is anything to say yes to leaves them there for good — while the agent reads the empty recall as the fact never having been stored. A failed count is said, not swallowed, but does not fail the read it is attached to. shell is the command the user types, which the MCP server learns from its install.
func (Outcome) Err ¶
Err is the failed notes as one error, or nil, for a surface whose exit status has to carry the failure.
func (Outcome) Text ¶
Text renders the notes as paragraphs to follow a result, a failure in parentheses so it reads as a remark on the result rather than a replacement for it.
func (Outcome) TextWithoutFailures ¶
TextWithoutFailures is Text less the failed notes, for a surface that reports those separately through Err.
type Promotion ¶ added in v0.5.5
type Promotion struct {
Proposed int // decisions put in the review queue as project memory
Superseded int // promoted decisions a later accepted one reversed
}
Promotion is what one PromoteDecisions pass did.
func PromoteDecisions ¶ added in v0.5.5
PromoteDecisions turns the decisions that hold on a project into proposed project memory, and supersedes a promoted one that a later promoted one reversed.
A decision lived only in checkpoints, and resume reads a handful of those: the project's settled questions fell out of every pack as soon as enough checkpoints had landed without restating them. A memory does not age out of a window. Proposed, not stored: the review queue is where a machine's conclusion waits for a person, or for the review switch — and that holds for a reversal too, which is proposed like any decision and replaces the old memory only once it is accepted.
Everything it reads is markdown — the checkpoints, and the memory timeline log.md restores — so a rebuilt index proposes nothing twice.
type RecallQuery ¶
type RecallQuery struct {
Query string
Limit int
Project string
Embed *provider.Provider // nil ranks by keyword alone
Model string
Shell string
// Dir is the repository the asker stands in, or "". A memory recorded at
// one of its commits is measured against it, and marked when a file it
// names has changed since.
Dir string
// Compact returns an id and one line per memory instead of the whole
// text, so an agent surveying what is known pays only for the memories it
// then asks for by id (RecallIDs).
Compact bool
}
RecallQuery is a recall as any surface asks it. Project "" searches every project; otherwise the project's memories plus the global ones.
type RecallResult ¶
type RecallResult struct {
Memories []Recalled `json:"memories"`
Project string `json:"project,omitempty"`
Outcome Outcome `json:"outcome"`
Compact bool `json:"compact,omitempty"`
}
func Recall ¶
func Recall(db *sql.DB, q RecallQuery) (RecallResult, error)
Recall answers a query from memory and reports the review queue alongside, which it adopts the user's hand edits to on the way.
func (RecallResult) Text ¶
func (r RecallResult) Text(ifEmpty string) string
Text renders the result, with ifEmpty standing in for the list when nothing matched — the one sentence a surface words for itself, since only it knows what its caller can do about it (a flag, a tool parameter).
type Recalled ¶
type Recalled struct {
memory.Memory
// NotDurable marks a memory the cache holds and the vault does not. It is
// still usable and still true — it is just one `rm -rf .logos` from gone,
// and the README tells people that command is safe. The write reported the
// failure once, to a caller that has since exited; every reader after
// that saw a row indistinguishable from a durable one. See
// memory.UnflushedIDs.
NotDurable bool `json:"not_durable,omitempty"`
}
Recalled is a memory as recall returns it, with where it is kept.
type RememberRequest ¶
type RememberRequest struct {
Memory memory.Memory
Embed *provider.Provider // nil dedups by exact text
Model string
// Dir is the repository the memory's project lives in, or "". Its HEAD is
// recorded with the memory so recall can later say when a file the memory
// names has changed since. "" records nothing, which is never flagged.
Dir string
}
type RememberResult ¶
type RememberResult struct {
Receipt memory.Receipt `json:"receipt"`
Outcome Outcome `json:"outcome"`
}
func Remember ¶
func Remember(db *sql.DB, req RememberRequest) (RememberResult, error)
Remember stores a memory. The error is for a write refused before anything was stored. A write the cache took and the vault did not is a result, not an error: the memory exists, recall returns it, and its id is the one handle anyone has to re-save or forget it — so the receipt comes back with the failure in its Outcome instead of being dropped for it.
type Searched ¶ added in v0.5.5
type Searched struct {
Project string `json:"project,omitempty"`
AllProjects bool `json:"all_projects,omitempty"`
}
Searched is one scope a lookup read. AllProjects stands for every project at once, which no single name can say.
Source Files