Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Changelog

## v0.9.0

- `mem-add` refuses (exit 2) an index line that does not link `<memory-name>.md`,
before writing anything. `<memory-name>` may carry `.md`. (#27)
- `mem-add <memory-name>` alone builds the line from the memory's frontmatter
(`name`, `description`); a missing file or description is refused (exit 2).
- `mem-verify` no longer answers `ok` for text that names a memory without
linking it: reachability is the `orphans` walk. A legacy record whose line has
no link is reported `MISSING` and not re-inserted. (#27)
14 changes: 12 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ happened to message and ask.
agentsync tell <resource> -- <text that begins with a dash>
agentsync messages [--max-age 24h] <resource>
agentsync forget <resource>
agentsync mem-add [--section "## Heading"] <memory-name> <index-line>
agentsync mem-add [--section "## Heading"] <memory-name> [<index-line>]
agentsync mem-verify [--repair=false]
agentsync orphans
agentsync mem-fold [--section H] [--hub NAME] [--dry-run]
Expand Down Expand Up @@ -155,8 +155,18 @@ path segment, so `go-tex` does not enclose `go-texinfo`.
`mem-add` takes a lease on the index, inserts once, and **reads the file back**
to confirm the line survived. Trusting the write would reproduce the bug.

`<memory-name>` is the file beside the index, with or without `.md`. The index
line must link it as `[title](<memory-name>.md)`; a line that does not is refused
with exit 2 before the index is touched (a text-only row points at nothing).
With no `<index-line>`, mem-add builds `- [name](x.md): description` from the
memory's frontmatter, and refuses (exit 2) naming the missing file or
`description`.

`mem-verify` re-reads every entry this session registered and puts back the ones
that vanished, in the section they came from.
that vanished, in the section they came from. An entry is `ok` only when its line
is in the index AND links a memory that the walk from `MEMORY.md` through hubs
reaches (the rule `orphans` uses); text that merely names a memory is reported
`MISSING`, and is not re-inserted when the recorded line has no link.

`orphans` reports the memories that NOTHING points at. It is the half
`mem-verify` cannot do: that one repairs what this session wrote, and a memory
Expand Down
94 changes: 90 additions & 4 deletions cmd/agentsync/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -260,17 +260,73 @@ func withIndexLease(fn func() error) error {
return fn()
}

// usageError is a refusal for bad arguments; main exits 2 for it, not 1.
type usageError struct{ error }

func (u usageError) Unwrap() error { return u.error }

// lineFromFrontmatter builds "- [title](name.md): description" from the
// memory's own frontmatter, and refuses naming what is missing.
func lineFromFrontmatter(path, name string) (string, error) {
b, err := os.ReadFile(path)
if err != nil {
return "", usageError{fmt.Errorf("cannot build an index line: %s.md is not readable (%v); give the line as a second argument", name, err)}
}
fm := map[string]string{}
lines := strings.Split(string(b), "\n")
if len(lines) > 0 && strings.TrimSpace(lines[0]) == "---" {
for _, l := range lines[1:] {
if strings.TrimSpace(l) == "---" {
break
}
if k, v, ok := strings.Cut(l, ":"); ok {
fm[strings.TrimSpace(k)] = strings.Trim(strings.TrimSpace(v), `"'`)
}
}
}
if fm["description"] == "" {
return "", usageError{fmt.Errorf("cannot build an index line: %s.md has no frontmatter `description`; add one or give the line as a second argument", name)}
}
title := fm["name"]
if title == "" {
title = name
}
return fmt.Sprintf("- [%s](%s.md): %s", title, name, fm["description"]), nil
}

func memAdd(args []string) error {
fs := flag.NewFlagSet("mem-add", flag.ExitOnError)
section := fs.String("section", "", "append at the end of this heading's section")
idx := fs.String("index", memoryIndex(), "path to MEMORY.md")
if err := fs.Parse(args); err != nil {
return err
}
if fs.NArg() != 2 {
return errors.New("usage: agentsync mem-add [--section H] <memory-name> <index-line>")
const usage = "usage: agentsync mem-add [--section H] <memory-name> [<index-line>]"
if fs.NArg() != 1 && fs.NArg() != 2 {
return usageError{errors.New(usage)}
}
// ⛔ The name is the file's stem; "x.md" is accepted and means "x". Passing
// the file name verbatim used to be recorded as "x.md" and match nothing.
name := strings.TrimSuffix(fs.Arg(0), ".md")
if name == "" || strings.ContainsAny(name, "/\\()") {
return usageError{fmt.Errorf("%s: %q is not a memory name (the file's name beside the index, without .md)", usage, fs.Arg(0))}
}
var line string
if fs.NArg() == 2 {
line = fs.Arg(1)
} else {
built, err := lineFromFrontmatter(filepath.Join(filepath.Dir(*idx), name+".md"), name)
if err != nil {
return err
}
line = built
}
// ⛔ agentsync#27: an index line that does not link the file is not an
// index line. mem-add reported "indexed" for text alone, and nothing
// pointed at the memory. Refuse BEFORE touching the index.
if !strings.Contains(line, "("+name+".md)") {
return usageError{fmt.Errorf("the index line must link the memory as [title](%s.md); %q does not (nothing would point at the file)", name, line)}
}
name, line := fs.Arg(0), fs.Arg(1)

err := withIndexLease(func() error {
b, err := os.ReadFile(*idx)
Expand Down Expand Up @@ -382,6 +438,19 @@ func reachedVia(r record, cache map[string]map[string]bool) bool {
return got[r.Name+".md"]
}

// lineReached reports whether the record's own line links a memory that the
// walk from the index reaches.
func lineReached(r record, cache map[string]map[string]bool) bool {
reachedVia(r, cache) // fills the cache for this index
got := cache[r.Index]
for _, m := range linkRE.FindAllStringSubmatch(r.Line, -1) {
if m[1] != "" && got[m[1]] {
return true
}
}
return false
}

func memVerify(args []string) error {
reach := map[string]map[string]bool{}
fs := flag.NewFlagSet("mem-verify", flag.ExitOnError)
Expand All @@ -405,7 +474,13 @@ func memVerify(args []string) error {
return err
}

if strings.Contains(string(b), r.Line) {
// ⛔ agentsync#27: the recorded text being in the index is NOT
// reachability -- a line with no link names a memory nothing points at,
// and this used to answer "ok" for it. "ok" now needs the line to be
// present AND to link a memory the walk from the index reaches (the one
// definition orphans uses). A walk that could not read says nothing
// either way, so it falls through to the checks below.
if strings.Contains(string(b), r.Line) && lineReached(r, reach) {
fmt.Printf("ok %s\n", r.Name)
continue
}
Expand Down Expand Up @@ -488,6 +563,12 @@ func memVerify(args []string) error {
fmt.Printf("MISSING %s\n", r.Name)
continue
}
// A record from before mem-add refused linkless lines: re-inserting its
// text would repeat the bug, so say what is needed instead.
if !strings.Contains(r.Line, "("+r.Name+".md)") {
fmt.Printf("MISSING %s (the recorded line has no link; add one with: agentsync mem-add %s)\n", r.Name, r.Name)
continue
}
if err := withIndexLease(func() error {
b, err := os.ReadFile(r.Index)
if err != nil {
Expand Down Expand Up @@ -875,6 +956,11 @@ func main() {
os.Exit(2)
}
if err := fn(os.Args[2:]); err != nil {
var ue usageError
if errors.As(err, &ue) {
fmt.Fprintln(os.Stderr, "agentsync:", err)
os.Exit(2)
}
if errors.Is(err, errUnavailable) {
os.Exit(1) // a refusal is a result, not a crash
}
Expand Down
171 changes: 171 additions & 0 deletions cmd/agentsync/memadd_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,171 @@
package main

import (
"errors"
"os"
"path/filepath"
"strings"
"testing"
)

// agentsync#27: `mem-add file.md "<text>"` printed "indexed" and appended the
// text alone, with no link; mem-verify then called the memory reachable.

func memEnv(t *testing.T) (dir, index string) {
t.Helper()
dir = t.TempDir()
index = filepath.Join(dir, "MEMORY.md")
t.Setenv("AGENTSYNC_DIR", filepath.Join(t.TempDir(), "state"))
t.Setenv("AGENTSYNC_MEMORY", index)
t.Setenv("AGENTSYNC_OWNER", "test-session")
writeMem(t, dir, "MEMORY.md", "# Memory index\n\n## Lessons\n")
return dir, index
}

func indexText(t *testing.T, index string) string {
t.Helper()
b, err := os.ReadFile(index)
if err != nil {
t.Fatal(err)
}
return string(b)
}

func isUsage(err error) bool {
var u usageError
return errors.As(err, &u)
}

func TestMemAddRefusesALineThatDoesNotLinkTheFile(t *testing.T) {
for _, name := range []string{"a-lesson", "a-lesson.md"} {
t.Run(name, func(t *testing.T) {
dir, index := memEnv(t)
writeMem(t, dir, "a-lesson.md", "---\nname: a-lesson\ndescription: d\n---\nbody\n")
err := memAdd([]string{name, "⛔ plain text, no link"})
if !isUsage(err) {
t.Fatalf("want a usage refusal (exit 2), got %v", err)
}
if !strings.Contains(err.Error(), "(a-lesson.md)") {
t.Errorf("refusal does not name the missing link: %v", err)
}
if strings.Contains(indexText(t, index), "plain text") {
t.Errorf("wrote a line that links nothing:\n%s", indexText(t, index))
}
})
}
}

func TestMemAddAcceptsALinkedLineWithOrWithoutDotMd(t *testing.T) {
for _, name := range []string{"a-lesson", "a-lesson.md"} {
t.Run(name, func(t *testing.T) {
dir, index := memEnv(t)
writeMem(t, dir, "a-lesson.md", "body\n")
out := capture(t, func() {
if err := memAdd([]string{"--section", "## Lessons", name, "- [a lesson](a-lesson.md): why"}); err != nil {
t.Fatal(err)
}
})
if !strings.Contains(out, "indexed a-lesson") {
t.Errorf("output %q", out)
}
if !strings.Contains(indexText(t, index), "- [a lesson](a-lesson.md): why") {
t.Errorf("row missing:\n%s", indexText(t, index))
}
verify := capture(t, func() { _ = memVerify(nil) })
if !strings.Contains(verify, "ok a-lesson") {
t.Errorf("verify: %s", verify)
}
})
}
}

func TestMemAddBuildsTheLinkFromTheFrontmatter(t *testing.T) {
dir, index := memEnv(t)
writeMem(t, dir, "a-lesson.md", "---\nname: A lesson\ndescription: what it taught\n---\nbody\n")
capture(t, func() {
if err := memAdd([]string{"a-lesson.md"}); err != nil {
t.Fatal(err)
}
})
if !strings.Contains(indexText(t, index), "- [A lesson](a-lesson.md): what it taught") {
t.Errorf("built line wrong:\n%s", indexText(t, index))
}
if got := capture(t, func() { _ = memVerify(nil) }); !strings.Contains(got, "ok a-lesson") {
t.Errorf("verify: %s", got)
}
}

func TestMemAddOneArgRefusalsNameWhatIsMissing(t *testing.T) {
t.Run("no file", func(t *testing.T) {
_, index := memEnv(t)
err := memAdd([]string{"ghost"})
if !isUsage(err) || !strings.Contains(err.Error(), "ghost.md") {
t.Errorf("got %v", err)
}
if strings.Contains(indexText(t, index), "ghost") {
t.Error("wrote something for a missing file")
}
})
t.Run("no description", func(t *testing.T) {
dir, index := memEnv(t)
writeMem(t, dir, "bare.md", "---\nname: bare\n---\nbody\n")
err := memAdd([]string{"bare"})
if !isUsage(err) || !strings.Contains(err.Error(), "description") {
t.Errorf("got %v", err)
}
if strings.Contains(indexText(t, index), "bare") {
t.Error("wrote something without a description")
}
})
t.Run("no arguments and three arguments", func(t *testing.T) {
memEnv(t)
if err := memAdd(nil); !isUsage(err) {
t.Errorf("no args: %v", err)
}
if err := memAdd([]string{"a", "b", "c"}); !isUsage(err) {
t.Errorf("three args: %v", err)
}
})
}

// mem-verify must not trust its own record: text in the index that names the
// memory without linking it is not reachability.
func TestMemVerifyDoesNotCallPlainTextReachable(t *testing.T) {
dir, index := memEnv(t)
writeMem(t, dir, "a-lesson.md", "body\n")
capture(t, func() {
if err := memAdd([]string{"a-lesson", "- [a lesson](a-lesson.md): why"}); err != nil {
t.Fatal(err)
}
})
_ = index
// A neighbour rewrites the row so the link is gone; the recorded line is
// no longer a substring either, but a variant that keeps the TEXT must
// not count: record the text-only form to model the legacy bug.
if err := saveRecords([]record{{Name: "a-lesson", Line: "a-lesson: why", Section: "## Lessons", Index: index}}); err != nil {
t.Fatal(err)
}
writeMem(t, dir, "MEMORY.md", "# Memory index\n\n## Lessons\n- a-lesson: why\n")
out := capture(t, func() { _ = memVerify([]string{"--repair=false"}) })
if strings.Contains(out, "still reachable") || strings.Contains(out, "ok a-lesson") {
t.Errorf("called an unlinked memory reachable:\n%s", out)
}
}

// A legacy record whose line has no link is text-only: it must be reported,
// not "ok", even though the text sits in the index.
func TestMemVerifyReportsALegacyLinklessRecord(t *testing.T) {
dir, _ := memEnv(t)
writeMem(t, dir, "a-lesson.md", "body\n")
writeMem(t, dir, "MEMORY.md", "# Memory index\n\n## Lessons\n⛔ plain text only\n")
if err := saveRecords([]record{{Name: "a-lesson", Line: "⛔ plain text only", Section: "## Lessons", Index: filepath.Join(dir, "MEMORY.md")}}); err != nil {
t.Fatal(err)
}
out := capture(t, func() { _ = memVerify([]string{"--repair=false"}) })
if strings.Contains(out, "still reachable") || strings.Contains(out, "ok a-lesson") {
t.Errorf("text-only line called reachable:\n%s", out)
}
if !strings.Contains(out, "MISSING a-lesson") {
t.Errorf("not reported:\n%s", out)
}
}
Loading