Merge pull request #309 from Gentleman-Programming/feat/auto-capture-save-prompts

feat(mcp): auto-capture prompt context on save

Author: Alan-TheGentleman

DOCS.md

@@ -605,6 +605,7 @@ Save structured observations. The tool description teaches agents the format:
 - **type**: `decision` | `architecture` | `bugfix` | `pattern` | `config` | `discovery` | `learning`
 - **scope**: `project` (default) | `personal`
 - **topic_key**: optional canonical topic id (e.g. `architecture/auth-model`) used to upsert evolving memories
+- **capture_prompt**: optional boolean, default `true`; when current prompt context is available for the same project/session, Engram records it alongside the observation. Automated pipeline saves such as SDD artifacts should pass `false`.
 - **content**: Structured with `**What**`, `**Why**`, `**Where**`, `**Learned**`
 
 Exact duplicate saves are deduplicated in a rolling time window using a normalized content hash + project + scope + type + title.
@@ -625,6 +626,7 @@ Delete an observation by ID. Uses soft-delete by default (`deleted_at`); optiona
 ### mem_save_prompt
 
 Save user prompts — records what the user asked so future sessions have context about user goals.
+When called in the same MCP process, this also feeds the current prompt context used by later `mem_save` calls with `capture_prompt=true`.
 
 ### mem_context
 

docs/ARCHITECTURE.md

@@ -53,7 +53,7 @@ Next session starts → Previous session context is injected automatically
 
 | Tool | Purpose |
 |------|---------|
-| `mem_save` | Save a structured observation (decision, bugfix, pattern, etc.) |
+| `mem_save` | Save a structured observation (decision, bugfix, pattern, etc.); automatically captures the current prompt when one is available unless `capture_prompt=false` |
 | `mem_update` | Update an existing observation by ID |
 | `mem_delete` | Delete an observation (soft-delete by default, hard-delete optional) |
 | `mem_suggest_topic_key` | Suggest a stable `topic_key` for evolving topics before saving |
@@ -88,6 +88,7 @@ Token-efficient memory retrieval — don't dump everything, drill in:
 
 - `mem_save` now supports `scope` (`project` default, `personal` optional)
 - `mem_save` also supports `topic_key`; with a topic key, saves become upserts (same project+scope+topic updates the existing memory)
+- `mem_save` supports `capture_prompt` (`true` by default). When the MCP process has current prompt context for the same project and session, it records that prompt alongside the observation. Automated saves such as SDD artifacts should pass `capture_prompt=false`.
 - Exact dedupe prevents repeated inserts in a rolling window (hash + project + scope + type + title)
 - Duplicates update metadata (`duplicate_count`, `last_seen_at`, `updated_at`) instead of creating new rows
 - Topic upserts increment `revision_count` so evolving decisions stay in one memory

docs/PLUGINS.md

@@ -256,6 +256,12 @@ When `mem_save` detects candidates, the JSON response includes:
 
 Old clients that read only the `result` string continue to work — these fields are additive.
 
+### mem_save prompt capture
+
+`mem_save` accepts `capture_prompt` as an optional boolean. The default is `true`: if the MCP process already has the current user prompt for the same project and session, Engram stores it in `user_prompts` using exact project + session + content dedupe. Passing `capture_prompt=false` skips that prompt capture path and is intended for automated artifacts such as SDD progress saves.
+
+If no current prompt is available to the MCP process, `mem_save` still succeeds and no prompt is invented from the observation content. Plugins/protocol hooks that can observe user prompts must feed that prompt context before relying on automatic capture. Calling `mem_save_prompt` in the same MCP process records the prompt and makes it available to later `mem_save` calls for the same project/session.
+
 ---
 
 ## Admin Observability (conflict layer)

internal/mcp/activity.go

@@ -19,6 +19,12 @@ type sessionState struct {
 	toolCallCount int
 	saveCount     int
 	startedAt     time.Time
+	currentPrompt *promptContext
+}
+
+type promptContext struct {
+	project string
+	content string
 }
 
 // NewSessionActivity creates a new activity tracker with the given nudge threshold.
@@ -63,6 +69,31 @@ func (a *SessionActivity) RecordSave(sessionID string) {
 	s.lastSaveAt = a.now()
 }
 
+// RecordPrompt stores the latest user prompt observed for a session. MCP does
+// not currently receive user prompts on every tool call, so callers must feed
+// this explicitly when prompt text is available.
+func (a *SessionActivity) RecordPrompt(sessionID, project, content string) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	s := a.getOrCreate(sessionID)
+	s.currentPrompt = &promptContext{project: project, content: content}
+}
+
+// CurrentPrompt returns the latest prompt for the session when it belongs to the
+// same project as the save operation.
+func (a *SessionActivity) CurrentPrompt(sessionID, project string) (string, bool) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	s, ok := a.sessions[sessionID]
+	if !ok || s.currentPrompt == nil {
+		return "", false
+	}
+	if s.currentPrompt.project != project || s.currentPrompt.content == "" {
+		return "", false
+	}
+	return s.currentPrompt.content, true
+}
+
 // NudgeIfNeeded returns a reminder string if too much time has passed since
 // the last save in this session. Returns empty string if no nudge needed.
 func (a *SessionActivity) NudgeIfNeeded(sessionID string) string {

internal/mcp/mcp.go

@@ -335,6 +335,9 @@ Examples:
 				mcp.WithString("project_choice_reason",
 					mcp.Description("Must be user_selected_after_ambiguous_project, and only after the user explicitly chose one of available_projects from an ambiguous_project error."),
 				),
+				mcp.WithBoolean("capture_prompt",
+					mcp.Description("Automatically capture the current user prompt when available (default: true). Set false for SDD artifacts or automated saves."),
+				),
 			),
 			queuedWriteHandler(writeQueue, handleSave(s, cfg, activity)),
 		)
@@ -447,7 +450,7 @@ Examples:
 					mcp.Description("Must be user_selected_after_ambiguous_project, and only after the user explicitly chose one of available_projects from an ambiguous_project error."),
 				),
 			),
-			queuedWriteHandler(writeQueue, handleSavePrompt(s, cfg)),
+			queuedWriteHandler(writeQueue, handleSavePrompt(s, cfg, activity)),
 		)
 	}
 
@@ -1011,6 +1014,7 @@ func handleSave(s *store.Store, cfg MCPConfig, activity *SessionActivity) server
 		topicKey, _ := req.GetArguments()["topic_key"].(string)
 		projectChoice, _ := req.GetArguments()["project"].(string)
 		projectChoiceReason, _ := req.GetArguments()["project_choice_reason"].(string)
+		capturePrompt := boolArg(req, "capture_prompt", true)
 
 		// Auto-detect project from cwd; only allow explicit user-selected recovery
 		// after ErrAmbiguousProject (issue #306).
@@ -1071,6 +1075,18 @@ func handleSave(s *store.Store, cfg MCPConfig, activity *SessionActivity) server
 			return mcp.NewToolResultError("Failed to save: " + err.Error()), nil
 		}
 
+		if capturePrompt && activity != nil {
+			if prompt, ok := activity.CurrentPrompt(sessionID, project); ok {
+				if _, _, promptErr := s.AddPromptIfMissing(store.AddPromptParams{
+					SessionID: sessionID,
+					Content:   prompt,
+					Project:   project,
+				}); promptErr != nil {
+					fmt.Fprintf(os.Stderr, "engram: auto prompt capture error (non-fatal): %v\n", promptErr)
+				}
+			}
+		}
+
 		activity.RecordSave(defaultSessionID(project))
 
 		msg := fmt.Sprintf("Memory saved: %q (%s)", title, typ)
@@ -1243,7 +1259,7 @@ func handleDelete(s *store.Store) server.ToolHandlerFunc {
 	}
 }
 
-func handleSavePrompt(s *store.Store, cfg MCPConfig) server.ToolHandlerFunc {
+func handleSavePrompt(s *store.Store, cfg MCPConfig, activity *SessionActivity) server.ToolHandlerFunc {
 	return func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 		content, _ := req.GetArguments()["content"].(string)
 		sessionID, _ := req.GetArguments()["session_id"].(string)
@@ -1272,6 +1288,10 @@ func handleSavePrompt(s *store.Store, cfg MCPConfig) server.ToolHandlerFunc {
 			return mcp.NewToolResultError("Failed to save prompt: " + err.Error()), nil
 		}
 
+		if activity != nil {
+			activity.RecordPrompt(sessionID, project, content)
+		}
+
 		detRes.Project = project
 		return respondWithProject(detRes, fmt.Sprintf("Prompt saved: %q", truncate(content, 80)), nil), nil
 	}

internal/mcp/mcp_test.go

@@ -139,6 +139,150 @@ func TestHandleSaveSuggestsTopicKeyWhenMissing(t *testing.T) {
 	}
 }
 
+func TestHandleSaveAutoCapturesCurrentPromptByDefault(t *testing.T) {
+	s := newMCPTestStore(t)
+	activity := NewSessionActivity(10 * time.Minute)
+	sessionID := defaultSessionID("engram")
+	activity.RecordPrompt(sessionID, "engram", "please persist the auth decision")
+	h := handleSave(s, MCPConfig{}, activity)
+
+	req := mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
+		"title":   "Auth decision",
+		"content": "**What**: chose auth boundary\n**Why**: user asked",
+		"type":    "decision",
+		"project": "engram",
+	}}}
+
+	res, err := h(context.Background(), req)
+	if err != nil {
+		t.Fatalf("handler error: %v", err)
+	}
+	if res.IsError {
+		t.Fatalf("unexpected save error: %s", callResultText(t, res))
+	}
+
+	prompts, err := s.RecentPrompts("engram", 5)
+	if err != nil {
+		t.Fatalf("recent prompts: %v", err)
+	}
+	if len(prompts) != 1 {
+		t.Fatalf("expected one auto-captured prompt, got %d: %#v", len(prompts), prompts)
+	}
+	if prompts[0].SessionID != sessionID || prompts[0].Content != "please persist the auth decision" {
+		t.Fatalf("unexpected prompt row: %#v", prompts[0])
+	}
+
+	// Saving another observation in the same session should reuse the prompt row,
+	// not duplicate exact same project+session+content context.
+	res, err = h(context.Background(), req)
+	if err != nil || res.IsError {
+		t.Fatalf("second save failed: err=%v isError=%v text=%q", err, res.IsError, callResultText(t, res))
+	}
+	prompts, err = s.RecentPrompts("engram", 5)
+	if err != nil {
+		t.Fatalf("recent prompts after second save: %v", err)
+	}
+	if len(prompts) != 1 {
+		t.Fatalf("expected prompt dedupe to keep one row, got %d: %#v", len(prompts), prompts)
+	}
+}
+
+func TestHandleSavePromptFeedsAutoCaptureContext(t *testing.T) {
+	s := newMCPTestStore(t)
+	activity := NewSessionActivity(10 * time.Minute)
+	savePrompt := handleSavePrompt(s, MCPConfig{}, activity)
+	save := handleSave(s, MCPConfig{}, activity)
+
+	promptRes, err := savePrompt(context.Background(), mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
+		"content": "user asked for prompt-linked bugfix memory",
+		"project": "engram",
+	}}})
+	if err != nil {
+		t.Fatalf("save prompt handler error: %v", err)
+	}
+	if promptRes.IsError {
+		t.Fatalf("unexpected save prompt error: %s", callResultText(t, promptRes))
+	}
+
+	saveRes, err := save(context.Background(), mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
+		"title":   "Prompt linked bugfix",
+		"content": "**What**: linked prompt context\n**Why**: user asked",
+		"type":    "bugfix",
+		"project": "engram",
+	}}})
+	if err != nil {
+		t.Fatalf("save handler error: %v", err)
+	}
+	if saveRes.IsError {
+		t.Fatalf("unexpected save error: %s", callResultText(t, saveRes))
+	}
+
+	prompts, err := s.RecentPrompts("engram", 5)
+	if err != nil {
+		t.Fatalf("recent prompts: %v", err)
+	}
+	if len(prompts) != 1 {
+		t.Fatalf("expected mem_save_prompt row to feed auto-capture without duplicate, got %d: %#v", len(prompts), prompts)
+	}
+	if prompts[0].Content != "user asked for prompt-linked bugfix memory" {
+		t.Fatalf("unexpected prompt content: %#v", prompts[0])
+	}
+}
+
+func TestHandleSaveCapturePromptFalseSkipsCurrentPrompt(t *testing.T) {
+	s := newMCPTestStore(t)
+	activity := NewSessionActivity(10 * time.Minute)
+	activity.RecordPrompt(defaultSessionID("engram"), "engram", "do not capture this prompt")
+	h := handleSave(s, MCPConfig{}, activity)
+
+	res, err := h(context.Background(), mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
+		"title":          "SDD artifact",
+		"content":        "## Apply progress",
+		"type":           "architecture",
+		"project":        "engram",
+		"capture_prompt": false,
+	}}})
+	if err != nil {
+		t.Fatalf("handler error: %v", err)
+	}
+	if res.IsError {
+		t.Fatalf("unexpected save error: %s", callResultText(t, res))
+	}
+
+	prompts, err := s.RecentPrompts("engram", 5)
+	if err != nil {
+		t.Fatalf("recent prompts: %v", err)
+	}
+	if len(prompts) != 0 {
+		t.Fatalf("expected opt-out to skip prompt capture, got %#v", prompts)
+	}
+}
+
+func TestHandleSaveNoCurrentPromptStillSucceeds(t *testing.T) {
+	s := newMCPTestStore(t)
+	h := handleSave(s, MCPConfig{}, NewSessionActivity(10*time.Minute))
+
+	res, err := h(context.Background(), mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
+		"title":   "No prompt available",
+		"content": "**What**: saved without prompt context",
+		"type":    "discovery",
+		"project": "engram",
+	}}})
+	if err != nil {
+		t.Fatalf("handler error: %v", err)
+	}
+	if res.IsError {
+		t.Fatalf("unexpected save error: %s", callResultText(t, res))
+	}
+	prompts, err := s.RecentPrompts("engram", 5)
+	if err != nil {
+		t.Fatalf("recent prompts: %v", err)
+	}
+	if len(prompts) != 0 {
+		t.Fatalf("expected no prompt rows when no current prompt is available, got %#v", prompts)
+	}
+}
+
 func TestHandleSaveDoesNotSuggestWhenTopicKeyProvided(t *testing.T) {
 	s := newMCPTestStore(t)
 	h := handleSave(s, MCPConfig{}, NewSessionActivity(10*time.Minute))
@@ -412,7 +556,7 @@ func TestHandlePromptContextStatsTimelineAndSessionHandlers(t *testing.T) {
 		t.Fatalf("add observation: %v", err)
 	}
 
-	savePrompt := handleSavePrompt(s, MCPConfig{})
+	savePrompt := handleSavePrompt(s, MCPConfig{}, nil)
 	savePromptReq := mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
 		"content": "how do we fix auth race conditions?",
 		"project": "engram",
@@ -626,7 +770,7 @@ func TestMCPHandlersReturnErrorsWhenStoreClosed(t *testing.T) {
 		t.Fatalf("expected delete to return tool error when store is closed")
 	}
 
-	promptRes, err := handleSavePrompt(s, MCPConfig{})(context.Background(), mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{"content": "prompt", "project": "engram"}}})
+	promptRes, err := handleSavePrompt(s, MCPConfig{}, nil)(context.Background(), mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{"content": "prompt", "project": "engram"}}})
 	if err != nil {
 		t.Fatalf("closed store save prompt call: %v", err)
 	}
@@ -1896,7 +2040,7 @@ func TestHandleSaveCreatesProjectScopedSession(t *testing.T) {
 
 func TestHandleSavePromptCreatesProjectScopedSession(t *testing.T) {
 	s := newMCPTestStore(t)
-	h := handleSavePrompt(s, MCPConfig{})
+	h := handleSavePrompt(s, MCPConfig{}, nil)
 
 	// Set up a git repo so auto-detect returns a known project.
 	dir := t.TempDir()
@@ -3130,7 +3274,7 @@ func TestMemSavePrompt_AmbiguousWithValidUserChoiceSucceeds(t *testing.T) {
 	t.Chdir(parent)
 
 	s := newMCPTestStore(t)
-	h := handleSavePrompt(s, MCPConfig{})
+	h := handleSavePrompt(s, MCPConfig{}, nil)
 	res, err := h(context.Background(), mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
 		"content":               "prompt after user chose repo-prompt-a",
 		"project":               "repo-prompt-a",
@@ -3164,7 +3308,7 @@ func TestMemSavePrompt_AmbiguousWithInventedProjectRejected(t *testing.T) {
 	t.Chdir(parent)
 
 	s := newMCPTestStore(t)
-	h := handleSavePrompt(s, MCPConfig{})
+	h := handleSavePrompt(s, MCPConfig{}, nil)
 	res, err := h(context.Background(), mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
 		"content":               "prompt must not save",
 		"project":               "invented-prompt-project",
@@ -3611,7 +3755,7 @@ func TestHandleSaveAndPromptUseConfigProjectForWrites(t *testing.T) {
 		t.Fatalf("expected mem_save config envelope, got %v", body)
 	}
 
-	prompt := handleSavePrompt(s, MCPConfig{})
+	prompt := handleSavePrompt(s, MCPConfig{}, nil)
 	res, err = prompt(context.Background(), mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
 		"content": "prompt saved under config project",
 		"project": "attempted-override", "project_choice_reason": project.SourceUserSelectedAfterAmbiguousProject,
@@ -3932,6 +4076,20 @@ func TestMemSessionSummary_SchemaNoProjectField(t *testing.T) {
 	}
 }
 
+func TestMemSaveSchemaIncludesCapturePrompt(t *testing.T) {
+	s := newMCPTestStore(t)
+	srv := NewServer(s)
+
+	st := srv.GetTool("mem_save")
+	if st == nil {
+		t.Fatal("mem_save not registered")
+	}
+	props := st.Tool.InputSchema.Properties
+	if _, ok := props["capture_prompt"]; !ok {
+		t.Fatal("mem_save schema must include capture_prompt")
+	}
+}
+
 // TestMemSessionSummary_AutoDetectsProject: summary is stored under the auto-detected project.
 func TestMemSessionSummary_AutoDetectsProject(t *testing.T) {
 	dir := t.TempDir()