Add search, update, categories, and default path to memory tool

- Add search_memories tool (keyword search with AND logic, optional category filter)
- Add update_memory tool (edit existing memories by ID)
- Add optional category field to memories for organization
- Default memory path to ~/.cagent/memory/<config-name>/memory.db (per-user, per-agent-config)
- Make path optional in config validation (was required, now defaults)
- Add configName parameter to ToolsetCreator for per-config-file identity
- SQLite migration adds category column transparently to existing databases
- Expand tool instructions with guidance on search vs get_all, update vs create

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: nunocoracao

docs/configuration/tools/index.md

@@ -101,17 +101,29 @@ toolsets:
 
 ### Memory
 
-Persistent key-value storage backed by SQLite. Data survives across sessions, letting agents remember context, user preferences, and past decisions.
+Persistent key-value storage backed by SQLite. Data survives across sessions, letting agents remember context, user preferences, and past decisions. Memories can be organized with categories and searched by keyword.
+
+Each agent gets its own database at `~/.cagent/memory/<agent-name>/memory.db` by default.
 
 ```yaml
 toolsets:
   - type: memory
-    path: ./agent_memory.db # optional: custom database path
+    path: ./agent_memory.db # optional: override the default location
 ```
 
-| Property | Type   | Default   | Description                                                            |
-| -------- | ------ | --------- | ---------------------------------------------------------------------- |
-| `path`   | string | automatic | Path to the SQLite database file. If omitted, uses a default location. |
+| Property | Type   | Default                                      | Description                          |
+| -------- | ------ | -------------------------------------------- | ------------------------------------ |
+| `path`   | string | `~/.cagent/memory/<agent-name>/memory.db`    | Path to the SQLite database file     |
+
+| Operation          | Description                                                         |
+| ------------------ | ------------------------------------------------------------------- |
+| `add_memory`       | Store a new memory with optional category                           |
+| `get_memories`     | Retrieve all stored memories                                        |
+| `delete_memory`    | Delete a specific memory by ID                                      |
+| `search_memories`  | Search memories by keywords and/or category (more efficient than get_all) |
+| `update_memory`    | Update an existing memory's content and/or category by ID           |
+
+Memories support an optional `category` field (e.g., `preference`, `fact`, `project`, `decision`) for organization and filtering.
 
 ### Fetch
 

pkg/acp/registry.go

@@ -14,7 +14,7 @@ import (
 func createToolsetRegistry(agent *Agent) *teamloader.ToolsetRegistry {
 	registry := teamloader.NewDefaultToolsetRegistry()
 
-	registry.Register("filesystem", func(ctx context.Context, toolset latest.Toolset, parentDir string, runConfig *config.RuntimeConfig) (tools.ToolSet, error) {
+	registry.Register("filesystem", func(ctx context.Context, toolset latest.Toolset, parentDir string, runConfig *config.RuntimeConfig, _ string) (tools.ToolSet, error) {
 		wd := runConfig.WorkingDir
 		if wd == "" {
 			var err error

pkg/config/latest/validate.go

@@ -116,9 +116,7 @@ func (t *Toolset) validate() error {
 	case "shell":
 		// no additional validation needed
 	case "memory":
-		if t.Path == "" {
-			return errors.New("memory toolset requires a path to be set")
-		}
+		// path is optional; defaults to ~/.cagent/memory/<agent-name>/memory.db
 	case "tasks":
 		// path defaults to ./tasks.json if not set
 	case "mcp":

pkg/config/v2/validate.go

@@ -66,9 +66,7 @@ func (t *Toolset) validate() error {
 
 	switch t.Type {
 	case "memory":
-		if t.Path == "" {
-			return errors.New("memory toolset requires a path to be set")
-		}
+		// path is optional; defaults to ~/.cagent/memory/<agent-name>/memory.db
 	case "mcp":
 		count := 0
 		if t.Command != "" {

pkg/config/v3/validate.go

@@ -87,9 +87,7 @@ func (t *Toolset) validate() error {
 			return errors.New("sandbox requires at least one path to be set")
 		}
 	case "memory":
-		if t.Path == "" {
-			return errors.New("memory toolset requires a path to be set")
-		}
+		// path is optional; defaults to ~/.cagent/memory/<agent-name>/memory.db
 	case "mcp":
 		count := 0
 		if t.Command != "" {

pkg/config/v4/validate.go

@@ -110,9 +110,7 @@ func (t *Toolset) validate() error {
 			return errors.New("sandbox requires at least one path to be set")
 		}
 	case "memory":
-		if t.Path == "" {
-			return errors.New("memory toolset requires a path to be set")
-		}
+		// path is optional; defaults to ~/.cagent/memory/<agent-name>/memory.db
 	case "mcp":
 		count := 0
 		if t.Command != "" {

pkg/config/v5/validate.go

@@ -113,9 +113,7 @@ func (t *Toolset) validate() error {
 			return errors.New("sandbox requires at least one path to be set")
 		}
 	case "memory":
-		if t.Path == "" {
-			return errors.New("memory toolset requires a path to be set")
-		}
+		// path is optional; defaults to ~/.cagent/memory/<agent-name>/memory.db
 	case "tasks":
 		// path defaults to ./tasks.json if not set
 	case "mcp":

pkg/config/validation_test.go

@@ -36,10 +36,6 @@ func TestValidationErrors(t *testing.T) {
 		name string
 		path string
 	}{
-		{
-			name: "memory toolset missing path",
-			path: "missing_memory_path_v2.yaml",
-		},
 		{
 			name: "path in non memory toolset",
 			path: "invalid_path_v2.yaml",

pkg/creator/agent.go

@@ -120,7 +120,7 @@ func createToolsetRegistry(workingDir string) *teamloader.ToolsetRegistry {
 	}
 
 	registry := teamloader.NewDefaultToolsetRegistry()
-	registry.Register("filesystem", func(context.Context, latest.Toolset, string, *config.RuntimeConfig) (tools.ToolSet, error) {
+	registry.Register("filesystem", func(context.Context, latest.Toolset, string, *config.RuntimeConfig, string) (tools.ToolSet, error) {
 		return tracker, nil
 	})
 

pkg/creator/agent_test.go

@@ -158,7 +158,7 @@ func TestFileWriteTracker(t *testing.T) {
 	require.NotNil(t, registry)
 
 	// Create the toolset through the registry
-	toolset, err := registry.CreateTool(ctx, latest.Toolset{Type: "filesystem"}, runConfig.WorkingDir, runConfig)
+	toolset, err := registry.CreateTool(ctx, latest.Toolset{Type: "filesystem"}, runConfig.WorkingDir, runConfig, "test-agent")
 	require.NoError(t, err)
 	require.NotNil(t, toolset)