Update: add memory management tools and enhance documentation for memory operations

louisho5 · louisho5 · commit ac480858659a · 2026-03-07T23:30:51.000+08:00
diff --git a/HOW_TO_START.md b/HOW_TO_START.md
@@ -165,17 +165,21 @@ This starts the agent loop, heartbeat, and any enabled channels (e.g., Telegram,
 
 ## Available Tools
 
-The agent has access to 11 tools:
+The agent has access to 15 tools:
 
 | Tool | Purpose |
-|------|---------|
+|------|--------|
 | `message` | Send messages to channels |
 | `filesystem` | Read, write, list files |
 | `exec` | Run shell commands |
 | `web` | Fetch web content from URLs |
 | `spawn` | Spawn background subagent |
 | `cron` | Schedule cron jobs |
 | `write_memory` | Persist information to memory |
+| `list_memory` | List all memory files |
+| `read_memory` | Read a specific memory file |
+| `edit_memory` | Find and replace text in a memory file |
+| `delete_memory` | Delete a daily memory file |
 | `create_skill` | Create a new skill |
 | `list_skills` | List available skills |
 | `read_skill` | Read a skill's content |
diff --git a/internal/agent/loop.go b/internal/agent/loop.go
@@ -97,8 +97,12 @@ func NewAgentLoop(b *chat.Hub, provider providers.LLMProvider, model string, max
 	sm := session.NewSessionManager(workspace)
 	ctx := NewContextBuilder(workspace, memory.NewLLMRanker(provider, model), 5)
 	mem := memory.NewMemoryStoreWithWorkspace(workspace, 100)
-	// register memory tool (needs store instance)
+	// register memory tools (all share the same store instance)
 	reg.Register(tools.NewWriteMemoryTool(mem))
+	reg.Register(tools.NewListMemoryTool(mem))
+	reg.Register(tools.NewReadMemoryTool(mem))
+	reg.Register(tools.NewEditMemoryTool(mem))
+	reg.Register(tools.NewDeleteMemoryTool(mem))
 
 	// register skill management tools (share the same os.Root)
 	skillMgr := tools.NewSkillManager(root)
diff --git a/internal/agent/memory/store.go b/internal/agent/memory/store.go
@@ -192,6 +192,86 @@ func (s *MemoryStore) GetRecentMemories(days int) (string, error) {
 	return strings.Join(parts, "\n---\n"), nil
 }
 
+// isValidMemoryFile reports whether name is a safe, recognised memory filename
+// (either "MEMORY.md" or a date file "YYYY-MM-DD.md").
+func isValidMemoryFile(name string) bool {
+	if name == "MEMORY.md" {
+		return true
+	}
+	// Must be exactly "YYYY-MM-DD.md" (13 chars).
+	if len(name) != 13 || name[4] != '-' || name[7] != '-' || name[10:] != ".md" {
+		return false
+	}
+	_, err := time.Parse("2006-01-02", name[:10])
+	return err == nil
+}
+
+// ListFiles returns the filenames of all files in the memory directory.
+func (s *MemoryStore) ListFiles() ([]string, error) {
+	entries, err := os.ReadDir(s.memoryDir)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return []string{}, nil
+		}
+		return nil, err
+	}
+	names := make([]string, 0, len(entries))
+	for _, e := range entries {
+		if !e.IsDir() {
+			names = append(names, e.Name())
+		}
+	}
+	return names, nil
+}
+
+// ReadFile reads a named file from the memory directory.
+// name must be "MEMORY.md" or a date file "YYYY-MM-DD.md".
+// Returns ("", nil) if the file does not exist.
+func (s *MemoryStore) ReadFile(name string) (string, error) {
+	if !isValidMemoryFile(name) {
+		return "", fmt.Errorf("invalid memory filename: %q", name)
+	}
+	b, err := os.ReadFile(filepath.Join(s.memoryDir, name))
+	if err != nil {
+		if os.IsNotExist(err) {
+			return "", nil
+		}
+		return "", err
+	}
+	return string(b), nil
+}
+
+// WriteFile writes content to a named file in the memory directory.
+// name must be "MEMORY.md" or a date file "YYYY-MM-DD.md".
+func (s *MemoryStore) WriteFile(name, content string) error {
+	if !isValidMemoryFile(name) {
+		return fmt.Errorf("invalid memory filename: %q", name)
+	}
+	if err := os.MkdirAll(s.memoryDir, 0o755); err != nil {
+		return err
+	}
+	return os.WriteFile(filepath.Join(s.memoryDir, name), []byte(content), 0o644)
+}
+
+// DeleteFile deletes a dated memory file (YYYY-MM-DD.md only).
+// Long-term memory (MEMORY.md) is protected and cannot be deleted via this method.
+func (s *MemoryStore) DeleteFile(name string) error {
+	// Only dated files may be deleted — never MEMORY.md.
+	if len(name) != 13 || name[4] != '-' || name[7] != '-' || name[10:] != ".md" {
+		return fmt.Errorf("delete_memory: only dated files (YYYY-MM-DD) can be deleted, got %q", name)
+	}
+	if _, err := time.Parse("2006-01-02", name[:10]); err != nil {
+		return fmt.Errorf("delete_memory: only dated files (YYYY-MM-DD) can be deleted, got %q", name)
+	}
+	if err := os.Remove(filepath.Join(s.memoryDir, name)); err != nil {
+		if os.IsNotExist(err) {
+			return fmt.Errorf("memory file not found: %q", name)
+		}
+		return err
+	}
+	return nil
+}
+
 // GetMemoryContext returns combined long-term memory + today's notes for the system prompt.
 func (s *MemoryStore) GetMemoryContext() (string, error) {
 	lt, err := s.ReadLongTerm()
diff --git a/internal/agent/tools/memory.go b/internal/agent/tools/memory.go
@@ -0,0 +1,219 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/local/picobot/internal/agent/memory"
+)
+
+// resolveMemoryTarget maps a user-friendly target to a memory filename.
+// target: "today", "long", or "YYYY-MM-DD".
+func resolveMemoryTarget(target string) (string, error) {
+	switch target {
+	case "today":
+		return time.Now().UTC().Format("2006-01-02") + ".md", nil
+	case "long":
+		return "MEMORY.md", nil
+	default:
+		if _, err := time.Parse("2006-01-02", target); err == nil {
+			return target + ".md", nil
+		}
+		return "", fmt.Errorf("invalid target %q: use 'today', 'long', or 'YYYY-MM-DD'", target)
+	}
+}
+
+// ─── list_memory ────
+
+// ListMemoryTool lists all files in the agent's memory directory.
+type ListMemoryTool struct {
+	mem *memory.MemoryStore
+}
+
+func NewListMemoryTool(mem *memory.MemoryStore) *ListMemoryTool {
+	return &ListMemoryTool{mem: mem}
+}
+
+func (t *ListMemoryTool) Name() string { return "list_memory" }
+func (t *ListMemoryTool) Description() string {
+	return "List all memory files (daily notes and long-term memory)"
+}
+func (t *ListMemoryTool) Parameters() map[string]interface{} { return nil }
+
+func (t *ListMemoryTool) Execute(ctx context.Context, args map[string]interface{}) (string, error) {
+	files, err := t.mem.ListFiles()
+	if err != nil {
+		return "", err
+	}
+	if len(files) == 0 {
+		return "No memory files found.", nil
+	}
+	today := time.Now().UTC().Format("2006-01-02") + ".md"
+	var sb strings.Builder
+	fmt.Fprintf(&sb, "Memory files (%d):\n", len(files))
+	for _, f := range files {
+		switch f {
+		case "MEMORY.md":
+			fmt.Fprintf(&sb, "- %s (long-term)\n", f)
+		case today:
+			fmt.Fprintf(&sb, "- %s (today)\n", f)
+		default:
+			fmt.Fprintf(&sb, "- %s\n", f)
+		}
+	}
+	return strings.TrimRight(sb.String(), "\n"), nil
+}
+
+// ─── read_memory ────
+
+// ReadMemoryTool reads the contents of a specific memory file.
+type ReadMemoryTool struct {
+	mem *memory.MemoryStore
+}
+
+func NewReadMemoryTool(mem *memory.MemoryStore) *ReadMemoryTool {
+	return &ReadMemoryTool{mem: mem}
+}
+
+func (t *ReadMemoryTool) Name() string        { return "read_memory" }
+func (t *ReadMemoryTool) Description() string { return "Read the contents of a memory file" }
+func (t *ReadMemoryTool) Parameters() map[string]interface{} {
+	return map[string]interface{}{
+		"type": "object",
+		"properties": map[string]interface{}{
+			"target": map[string]interface{}{
+				"type":        "string",
+				"description": "'today' for today's note, 'long' for long-term memory, or a date 'YYYY-MM-DD'",
+			},
+		},
+		"required": []string{"target"},
+	}
+}
+
+func (t *ReadMemoryTool) Execute(ctx context.Context, args map[string]interface{}) (string, error) {
+	target, ok := args["target"].(string)
+	if !ok || target == "" {
+		return "", fmt.Errorf("read_memory: 'target' argument required (today|long|YYYY-MM-DD)")
+	}
+	name, err := resolveMemoryTarget(target)
+	if err != nil {
+		return "", err
+	}
+	content, err := t.mem.ReadFile(name)
+	if err != nil {
+		return "", err
+	}
+	if content == "" {
+		return fmt.Sprintf("(%s is empty or does not exist)", name), nil
+	}
+	return content, nil
+}
+
+// ─── edit_memory ────
+
+// EditMemoryTool finds and replaces text within a memory file.
+type EditMemoryTool struct {
+	mem *memory.MemoryStore
+}
+
+func NewEditMemoryTool(mem *memory.MemoryStore) *EditMemoryTool {
+	return &EditMemoryTool{mem: mem}
+}
+
+func (t *EditMemoryTool) Name() string        { return "edit_memory" }
+func (t *EditMemoryTool) Description() string { return "Find and replace text within a memory file" }
+func (t *EditMemoryTool) Parameters() map[string]interface{} {
+	return map[string]interface{}{
+		"type": "object",
+		"properties": map[string]interface{}{
+			"target": map[string]interface{}{
+				"type":        "string",
+				"description": "'today', 'long', or 'YYYY-MM-DD'",
+			},
+			"old_text": map[string]interface{}{
+				"type":        "string",
+				"description": "Exact text to find and replace",
+			},
+			"new_text": map[string]interface{}{
+				"type":        "string",
+				"description": "Replacement text (omit or set to empty string to delete the matched text)",
+			},
+		},
+		"required": []string{"target", "old_text"},
+	}
+}
+
+func (t *EditMemoryTool) Execute(ctx context.Context, args map[string]interface{}) (string, error) {
+	target, ok := args["target"].(string)
+	if !ok || target == "" {
+		return "", fmt.Errorf("edit_memory: 'target' argument required (today|long|YYYY-MM-DD)")
+	}
+	oldText, ok := args["old_text"].(string)
+	if !ok || oldText == "" {
+		return "", fmt.Errorf("edit_memory: 'old_text' argument required")
+	}
+	newText, _ := args["new_text"].(string) // defaults to "" (deletion) if absent
+
+	name, err := resolveMemoryTarget(target)
+	if err != nil {
+		return "", err
+	}
+	content, err := t.mem.ReadFile(name)
+	if err != nil {
+		return "", err
+	}
+	if !strings.Contains(content, oldText) {
+		return "", fmt.Errorf("edit_memory: text not found in %s", name)
+	}
+	updated := strings.ReplaceAll(content, oldText, newText)
+	if err := t.mem.WriteFile(name, updated); err != nil {
+		return "", err
+	}
+	return fmt.Sprintf("edited %s", name), nil
+}
+
+// ─── delete_memory ────
+
+// DeleteMemoryTool deletes a dated daily memory file.
+// Long-term memory (MEMORY.md) will be protected.
+type DeleteMemoryTool struct {
+	mem *memory.MemoryStore
+}
+
+func NewDeleteMemoryTool(mem *memory.MemoryStore) *DeleteMemoryTool {
+	return &DeleteMemoryTool{mem: mem}
+}
+
+func (t *DeleteMemoryTool) Name() string { return "delete_memory" }
+func (t *DeleteMemoryTool) Description() string {
+	return "Delete a daily memory file (YYYY-MM-DD). Long-term memory (MEMORY.md) cannot be deleted this way."
+}
+func (t *DeleteMemoryTool) Parameters() map[string]interface{} {
+	return map[string]interface{}{
+		"type": "object",
+		"properties": map[string]interface{}{
+			"target": map[string]interface{}{
+				"type":        "string",
+				"description": "Date of the daily note to delete, in 'YYYY-MM-DD' format",
+			},
+		},
+		"required": []string{"target"},
+	}
+}
+
+func (t *DeleteMemoryTool) Execute(ctx context.Context, args map[string]interface{}) (string, error) {
+	target, ok := args["target"].(string)
+	if !ok || target == "" {
+		return "", fmt.Errorf("delete_memory: 'target' argument required (YYYY-MM-DD)")
+	}
+	// Only dated files are accepted — "long" / "today" are rejected here.
+	if _, err := time.Parse("2006-01-02", target); err != nil {
+		return "", fmt.Errorf("delete_memory: target must be a date in YYYY-MM-DD format, got %q", target)
+	}
+	if err := t.mem.DeleteFile(target + ".md"); err != nil {
+		return "", err
+	}
+	return fmt.Sprintf("deleted %s.md", target), nil
+}
diff --git a/internal/agent/tools/memory_test.go b/internal/agent/tools/memory_test.go
diff --git a/internal/config/onboard.go b/internal/config/onboard.go
