Merge pull request #19 from lazypower/feat/issue-12-memory-accountability

Memory accountability: retract verb (tombstone + supersession)

Author: lazypower

CLAUDE.md

@@ -11,6 +11,8 @@ Persistent memory for AI coding agents. Single Go binary, zero dependencies.
 - **L1 (`-b`)**: Max 2000 characters (~300 words). Primary context tier. Compress aggressively.
 - **L2 (`-d`)**: Max 40000 characters. Full content, retrieved on-demand only.
 
+**Memory is not immutable; it is accountable.** Wrong write, stale fact, captured a piece of PII you shouldn't have? Use `continuity retract <uri> --reason "..."` to mark it retracted. The memory stays in the tree as a marker but is excluded from default reads. Pass `--superseded-by <new-uri>` when you have a replacement to preserve trajectory. Operators don't run this verb — it exists for the agent to curate its own substrate. The trust contract is what governs the substrate, not architectural enforcement.
+
 ## What This Is
 
 Continuity gives Claude Code (and eventually any AI agent) memory that persists across sessions. It captures what happened, what was learned, and how you work — then injects that context into future sessions so the agent doesn't start cold every time.

README.md

@@ -235,20 +235,42 @@ continuity uninstall-service  Remove system service
 continuity hook <evt>         Handle Claude Code hook events
 continuity search             Search memories by query
 continuity remember    Store a memory directly (no LLM needed)
+continuity retract     Retract a memory you wrote (tombstone or supersession)
 continuity profile     Show relational profile
 continuity tree        Browse the memory tree
 continuity dedup       Deduplicate similar memory nodes
 continuity version     Print version information
 ```
 
+### Memory accountability
+
+Memory is not immutable; it is accountable. When a write turns out to be wrong, stale, or sensitive, the agent can retract it:
+
+```bash
+# Pure tombstone — preserved as a marker, hidden from default reads
+continuity retract mem://user/events/test-foo --reason "test repro, no ongoing value"
+
+# Supersession — link a successor to preserve the trail of how understanding evolved
+continuity retract mem://user/preferences/old-style \
+  --reason "preference changed after 2026-04 review" \
+  --superseded-by mem://user/preferences/new-style
+```
+
+Retracted memories stay in the tree — nothing is silently erased. Pass `--include-retracted` to `show` or `tree` to inspect them. The reason text is sequestered behind that flag (absent from default responses, not empty or redacted), so confronting your own past retraction is a deliberate act.
+
+The verb exists for the agent to curate its own substrate. Operators don't run it. The trust contract is what governs the substrate, not architectural enforcement.
+
 ## API
 
 All endpoints on `http://127.0.0.1:37777`:
 
 | Method | Path | Description |
 |--------|------|-------------|
 | `GET` | `/api/health` | Server health + uptime |
-| `GET` | `/api/tree?uri=` | Browse memory tree |
+| `GET` | `/api/tree?uri=&include_retracted=` | Browse memory tree |
+| `GET` | `/api/memories?uri=&include_retracted=` | Fetch a single memory |
+| `POST` | `/api/memories` | Store a memory directly |
+| `POST` | `/api/memories/retract` | Retract a memory (tombstone or supersession) |
 | `GET` | `/api/search?q=&mode=find\|search` | Query memories |
 | `GET` | `/api/profile` | Relational profile + preference nodes |
 | `GET` | `/api/context?session_id=` | Get injection context |

internal/cli/init.go

@@ -26,8 +26,11 @@ Your memory lives in continuity. Reach for it naturally:
 - Looking something up: ` + "`continuity search \"<query>\"`" + `
 - Browsing what you know: ` + "`continuity tree [uri]`" + `
 - Understanding who you're working with: ` + "`continuity profile`" + `
+- Retracting a memory you wrote: ` + "`continuity retract <uri> --reason \"...\"`" + ` (or with ` + "`--superseded-by`" + ` to link a successor)
 
 Before searching the codebase for prior decisions, conventions, or context — check continuity first. If you learn something worth keeping, store it immediately.
+
+**Memory is not immutable; it is accountable.** When a write you made turns out to be wrong, stale, or sensitive, retract it — the memory is preserved as a marker but excluded from default reads. Retraction is for *you*, the agent: operators don't run this verb. The trust contract is what governs the substrate, not enforcement at the CLI.
 `
 
 var initAutostart bool

internal/cli/remember.go

@@ -11,12 +11,13 @@ import (
 )
 
 var (
-	rememberCategory string
-	rememberName     string
-	rememberSummary  string
-	rememberBody     string
-	rememberDetail   string
-	rememberSession  string
+	rememberCategory             string
+	rememberName                 string
+	rememberSummary              string
+	rememberBody                 string
+	rememberDetail               string
+	rememberSession              string
+	rememberAcknowledgeRetracted bool
 )
 
 var validCategorySet = map[string]bool{
@@ -45,6 +46,7 @@ func init() {
 	rememberCmd.Flags().StringVarP(&rememberBody, "body", "b", "", "L1 overview — max 2000 chars, compress detail aggressively (required)")
 	rememberCmd.Flags().StringVarP(&rememberDetail, "detail", "d", "", "L2 full content — max 40000 chars (optional)")
 	rememberCmd.Flags().StringVar(&rememberSession, "session", "", "Session ID for provenance (optional)")
+	rememberCmd.Flags().BoolVar(&rememberAcknowledgeRetracted, "acknowledge-retracted", false, "Proceed past a dedup match against retracted memory (use after inspecting with `show --include-retracted`)")
 
 	rememberCmd.MarkFlagRequired("category")
 	rememberCmd.MarkFlagRequired("name")
@@ -67,7 +69,7 @@ func runRemember(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("continuity server is not running — start it with: continuity serve")
 	}
 
-	payload := map[string]string{
+	payload := map[string]any{
 		"category": rememberCategory,
 		"name":     rememberName,
 		"summary":  rememberSummary,
@@ -79,26 +81,55 @@ func runRemember(cmd *cobra.Command, args []string) error {
 	if rememberSession != "" {
 		payload["session_id"] = rememberSession
 	}
+	if rememberAcknowledgeRetracted {
+		payload["acknowledge_retracted"] = true
+	}
 
 	body, err := json.Marshal(payload)
 	if err != nil {
 		return fmt.Errorf("marshal: %w", err)
 	}
 
-	data, err := client.Post("/api/memories", body)
-	if err != nil {
-		return fmt.Errorf("remember: %w", err)
-	}
+	data, postErr := client.Post("/api/memories", body)
 
+	// data may carry a structured response on either path (success body or a
+	// non-2xx JSON error like 409 matches_retracted). Decode opportunistically:
+	// on the error path, a parse failure means the server returned something
+	// non-JSON and we fall back to the transport error; on the success path,
+	// a parse failure is a real bug we surface rather than printing empty fields.
 	var resp struct {
-		Status string `json:"status"`
-		URI    string `json:"uri"`
-		Error  string `json:"error"`
+		Status      string   `json:"status"`
+		URI         string   `json:"uri"`
+		MatchedURIs []string `json:"matched_uris"`
+		Hint        string   `json:"hint"`
+		Error       string   `json:"error"`
+	}
+	parseErr := json.Unmarshal(data, &resp)
+
+	if resp.Status == "matches_retracted" {
+		fmt.Fprintln(os.Stderr, "matches_retracted: candidate write matches retracted memory")
+		for _, u := range resp.MatchedURIs {
+			fmt.Fprintf(os.Stderr, "  - %s\n", u)
+		}
+		if resp.Hint != "" {
+			fmt.Fprintln(os.Stderr, resp.Hint)
+		}
+		os.Exit(2)
 	}
-	if err := json.Unmarshal(data, &resp); err != nil {
-		return fmt.Errorf("parse response: %w", err)
+
+	if postErr != nil {
+		// Non-2xx: prefer a structured server-side error message if we got one.
+		if parseErr == nil && resp.Error != "" {
+			return fmt.Errorf("%s", resp.Error)
+		}
+		return fmt.Errorf("remember: %w", postErr)
 	}
 
+	// Success path: a bad decode means the server returned something unexpected.
+	// Fail fast rather than printing empty fields.
+	if parseErr != nil {
+		return fmt.Errorf("parse response: %w", parseErr)
+	}
 	if resp.Error != "" {
 		fmt.Fprintf(os.Stderr, "error: %s\n", resp.Error)
 		os.Exit(1)

internal/cli/retract.go

@@ -0,0 +1,100 @@
+package cli
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/lazypower/continuity/internal/hooks"
+	"github.com/spf13/cobra"
+)
+
+var (
+	retractURI          string
+	retractReason       string
+	retractSupersededBy string
+)
+
+var retractCmd = &cobra.Command{
+	Use:   "retract <uri>",
+	Short: "Retract a memory (tombstone or supersession)",
+	Long: `Retract a memory you wrote. Memory is preserved as a marker but excluded from
+default reads — search, tree, context injection. Use --include-retracted on inspection
+commands to see retracted memories.
+
+A reason is required, kept short (one sentence). With --superseded-by, the retraction
+becomes a supersession: the new memory is reachable normally and the old is linked to it,
+preserving the trail of how understanding evolved.
+
+Examples:
+  continuity retract mem://user/events/test-foo \
+    --reason "test repro, no ongoing value"
+
+  continuity retract mem://user/preferences/old-style \
+    --reason "preference changed after 2026-04 review" \
+    --superseded-by mem://user/preferences/new-style`,
+	Args: cobra.ExactArgs(1),
+	RunE: runRetract,
+}
+
+func init() {
+	retractCmd.Flags().StringVarP(&retractReason, "reason", "r", "", "Why this memory is being retracted (required, one sentence)")
+	retractCmd.Flags().StringVar(&retractSupersededBy, "superseded-by", "", "URI of the memory that supersedes this one (optional)")
+	retractCmd.MarkFlagRequired("reason")
+}
+
+func runRetract(cmd *cobra.Command, args []string) error {
+	retractURI = strings.TrimSpace(args[0])
+	if !strings.HasPrefix(retractURI, "mem://") {
+		return fmt.Errorf("invalid URI %q: must start with mem://", retractURI)
+	}
+	if retractSupersededBy != "" && !strings.HasPrefix(retractSupersededBy, "mem://") {
+		return fmt.Errorf("invalid superseded-by URI %q: must start with mem://", retractSupersededBy)
+	}
+
+	client := hooks.NewClient()
+	if !client.Healthy() {
+		return fmt.Errorf("continuity server is not running — start it with: continuity serve")
+	}
+
+	payload := map[string]string{
+		"uri":    retractURI,
+		"reason": retractReason,
+	}
+	if retractSupersededBy != "" {
+		payload["superseded_by"] = retractSupersededBy
+	}
+
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return fmt.Errorf("marshal: %w", err)
+	}
+
+	data, err := client.Post("/api/memories/retract", body)
+	if err != nil {
+		return fmt.Errorf("retract: %w", err)
+	}
+
+	var resp struct {
+		Status       string `json:"status"`
+		URI          string `json:"uri"`
+		SupersededBy string `json:"superseded_by"`
+		Error        string `json:"error"`
+	}
+	if err := json.Unmarshal(data, &resp); err != nil {
+		return fmt.Errorf("parse response: %w", err)
+	}
+
+	if resp.Error != "" {
+		fmt.Fprintf(os.Stderr, "error: %s\n", resp.Error)
+		os.Exit(1)
+	}
+
+	if resp.SupersededBy != "" {
+		fmt.Printf("%s: %s → %s\n", resp.Status, resp.URI, resp.SupersededBy)
+	} else {
+		fmt.Printf("%s: %s\n", resp.Status, resp.URI)
+	}
+	return nil
+}