feat: persistent memory system with go-vector merge-on-write

Three-tier memory:
- Tier 1: Facts (user.md/env.md) with caps, security scan, agent-managed
- Tier 2: Buffer ring per session for turn-level context
- Tier 3: Episode summaries with search via SimpleCall

Merge-on-write uses go-vector RandomProjections for fast similarity:
cos>0.7 auto-merge, cos<0.3 auto-add, 0.3-0.7 LLM judgment
Saves ~80% LLM calls on memory writes.

57 tests, race clean, zero new dependencies beyond go-vector (also zero-dep).

Author: jkyberneees

cmd/kode/repl.go

@@ -123,12 +123,20 @@ func replCmd(args []string) error {
 		Renderer:       rend,
 		Skills:         skillsCfg,
 		SkillManager:   sm,
+		MemoryConfig:   resolved.Memory,
 	})
 	if err != nil {
 		return err
 	}
 	defer agent.Close()
 
+	// Restore buffer from session if resuming
+	if sess != nil && len(sess.Buffer) > 0 {
+		if mm := agent.Memory(); mm != nil {
+			mm.RestoreBuffer(sess.Buffer)
+		}
+	}
+
 	// Create session if not resuming one
 	if sess == nil {
 		sess, err = store.Create(
@@ -176,6 +184,15 @@ func replCmd(args []string) error {
 		origLen := len(messages)
 		messages = append(messages, llm.Message{Role: "user", Content: input})
 
+		// Append user input to buffer
+		if mm := agent.Memory(); mm != nil {
+			userSummary := input
+			if len(userSummary) > 100 {
+				userSummary = userSummary[:97] + "..."
+			}
+			mm.AppendBuffer("user", userSummary)
+		}
+
 		// Run agent with full history
 		rend.Start(input)
 		_, allMessages, err := agent.RunWithMessages(ctx, messages)
@@ -184,18 +201,46 @@ func replCmd(args []string) error {
 			continue
 		}
 
+		// Append agent response to buffer
+		if mm := agent.Memory(); mm != nil && len(allMessages) > 0 {
+			if last := allMessages[len(allMessages)-1]; last.Role == "assistant" {
+				summary := last.Content
+				if len(summary) > 100 {
+					summary = summary[:97] + "..."
+				}
+				mm.AppendBuffer("agent", summary)
+			}
+		}
+
 		// Save new messages to session
 		newMsgs := allMessages[origLen:]
 		if err := store.Append(sess.ID, newMsgs); err != nil {
 			fmt.Fprintf(os.Stderr, "kode: save error: %v\n", err)
 		}
 
-		// Reload session to get updated turn count
+		// Reload session to get updated turn count + persist buffer
 		sess, _ = store.Load(sess.ID)
+		if sess != nil {
+			if mm := agent.Memory(); mm != nil {
+				sess.Buffer = mm.GetBuffer()
+				store.Save(sess)
+			}
+		}
 		turn++
 
 		fmt.Fprintln(os.Stderr)
 	}
+
+	// Session end — extract episode if enough turns
+	if mm := agent.Memory(); mm != nil {
+		messages := sess.GetMessages()
+		msgStrs := make([]string, 0, len(messages))
+		for _, m := range messages {
+			msgStrs = append(msgStrs, m.Role+": "+m.Content)
+		}
+		mm.OnSessionEnd(sess.ID, sess.Turns, msgStrs)
+	}
+
 	return nil
 }
 

cmd/kode/serve.go

@@ -142,6 +142,7 @@ func newServeAgent(resolved config.ResolvedConfig, system string) (*kode.Agent,
 		Renderer:       nil, // silent — we stream via WebSocket
 		Skills:         &resolved.Skills,
 		SkillManager:   sm,
+		MemoryConfig:   resolved.Memory,
 	})
 	if err != nil {
 		return nil, nil, err

cmd/kode/subagent.go

@@ -335,6 +335,7 @@ func subagentCmd(args []string) error {
 		Renderer:       rend,
 		Skills:         &resolved.Skills,
 		SkillManager:   sm,
+		MemoryConfig:   resolved.Memory,
 	})
 	if err != nil {
 		return fmt.Errorf("create agent: %w", err)

docs/MEMORY.md

@@ -0,0 +1,140 @@
+# Memory System
+
+kode has a **three-tier file-based memory** system. Zero external dependencies beyond go-vector (which is also zero-dep).
+
+## Three Tiers
+
+```
+~/.kode/memory/
+├── facts/
+│   ├── user.md          ← Global user profile (1,500 chars)
+│   └── env.md           ← Global environment facts (2,500 chars)
+├── project-facts/       ← Optional per-project overrides (auto-layered)
+│   └── <path-hash>/
+│       ├── user.md
+│       └── env.md
+└── episodes/
+    ├── <session-id>.md  ← LLM-extracted summaries
+    └── index.json       ← Metadata for search
+```
+
+### Tier 1 — Facts (in system prompt)
+
+Two typed files, injected as frozen snapshot at session start. Managed by the agent via the `memory` tool.
+
+| Target | File | Cap | Purpose |
+|--------|------|-----|---------|
+| `user` | `facts/user.md` | 1,500 | User preferences, style, pet peeves |
+| `env` | `facts/env.md` | 2,500 | OS, tools, conventions, architecture |
+
+**Frozen snapshot:** Loaded once at agent start into the system prompt. Live writes via the `memory` tool persist to disk immediately but appear in the prompt next session. This preserves LLM prefix caching.
+
+### Tier 2 — Buffer (in session)
+
+Not a file. Lives in `Session.Buffer []string` — a ring buffer capped at 20 lines. The loop engine appends a one-line summary after each turn:
+
+```
+HH:MM  user   "fix TOCTOU race"
+HH:MM  agent  read file_tool.go, wrote security_e2e_test.go
+HH:MM  agent  pushed 19 tests, tagged v0.8.19
+```
+
+- Injected into system prompt only when non-empty.
+- Preserved across `kode continue` (serialized in session JSON).
+- Oldest evicted when cap reached.
+
+### Tier 3 — Episodes (on-disk, searchable)
+
+After sessions with ≥3 turns, the MemoryManager runs SimpleCall to extract 1-3 durable facts. Written to `episodes/<session-id>.md`. Searchable via `memory(search=...)` which uses SimpleCall to rank episodes by relevance to the query.
+
+## Memory Tool — Unified API
+
+```json
+{
+  "name": "memory",
+  "description": "Manage persistent memory across sessions.",
+  "parameters": {
+    "action": { "enum": ["add", "replace", "remove", "consolidate", "read", "search"] },
+    "target": { "enum": ["user", "env"], "description": "For add/replace/remove/consolidate" },
+    "content": { "type": "string", "description": "For add/replace" },
+    "old_text": { "type": "string", "description": "Unique substring for replace/remove" },
+    "query": { "type": "string", "description": "For search — facts + episodes" }
+  }
+}
+```
+
+### Actions
+
+| Action | Target | Content | old_text | Effect |
+|--------|--------|---------|----------|--------|
+| `add` | user/env | ✅ new entry | — | Appends to file. Check: dedup + cap + merge |
+| `replace` | user/env | ✅ replacement | ✅ substring | Finds entry by substring, replaces it |
+| `remove` | user/env | — | ✅ substring | Finds entry by substring, removes it |
+| `consolidate` | user/env | — | — | SimpleCall: merge related entries for density |
+| `read` | — | — | — | Returns full content of both user.md + env.md |
+| `search` | — | — | ✅ query | SimpleCall: rank episodes + facts by relevance |
+
+## Merge-on-Write (go-vector Integration)
+
+When adding a fact, a **two-tier merge detector** classifies the new entry:
+
+```
+RP.embed(newEntry) → cos similarity vs each existing entry
+
+  cos > 0.7 ──────────────────→ auto-merge (replace old + new)
+  cos < 0.3 ──────────────────→ auto-add (no conflict)
+  0.3 ≤ cos ≤ 0.7 ──→ SimpleCall judgment → merge or add
+```
+
+This saves ~80% of LLM calls on memory writes.
+
+**Implementation:** `internal/memory/merge.go` imports `github.com/BackendStack21/go-vector/pkg/vector` for `RandomProjections` and `Cosine`. The RP embedder is fit on existing facts when the detector is created, and re-fit whenever facts change.
+
+### Cold Start
+
+When `facts/user.md` and `facts/env.md` are empty (fresh install), no RP vocabulary exists. The merge detector gracefully returns "no corpus" and all adds pass through to SimpleCall. After the first few facts are written, the detector self-trains on re-fit.
+
+## Subagent Memory
+
+Subagents (separate OS processes via `kode subagent`) inherit a **read-only snapshot** of facts:
+
+```
+kode subagent --memory-snapshot /tmp/kode-mem-<rand>.json
+```
+
+The subagent's system prompt includes:
+```
+# Memory Context (read-only)
+── User Profile ──
+... (facts/user.md)
+── Environment ──
+... (facts/env.md)
+```
+
+Subagents do NOT get a `memory` tool — they cannot modify parent memory.
+
+## Config
+
+```json
+{
+  "memory": {
+    "enabled": true,
+    "facts_limit_user": 1500,
+    "facts_limit_env": 2500,
+    "buffer_lines": 20,
+    "buffer_enabled": true,
+    "merge_on_write": true,
+    "extract_threshold": 3,
+    "project_facts": false
+  }
+}
+```
+
+## Security
+
+All memory content is scanned on write for:
+- **Invisible Unicode** (zero-width spaces, RTL override, etc.)
+- **Injection patterns** (prompt injection markers)
+- **Credential patterns** (`sk-...`, `-----BEGIN`, bearer tokens)
+
+Rejected content returns an error to the agent.

go.mod

@@ -1,3 +1,5 @@
 module github.com/BackendStack21/kode
 
-go 1.22
+go 1.24.3
+
+require github.com/BackendStack21/go-vector v1.1.1 // indirect

go.sum

@@ -0,0 +1,2 @@
+github.com/BackendStack21/go-vector v1.1.1 h1:sycI+a/ifT2DD3kdH0HleWtjKmIVNutvL/pgOL9qTA8=
+github.com/BackendStack21/go-vector v1.1.1/go.mod h1:+IzfAFO4m6xrjsOhZsiTAbMbm8+hX0d9C1uD0SGPzHc=

internal/config/loader.go

@@ -19,6 +19,7 @@ import (
 	"strconv"
 
 	"github.com/BackendStack21/kode/internal/danger"
+	"github.com/BackendStack21/kode/internal/memory"
 	"github.com/BackendStack21/kode/internal/skills"
 )
 
@@ -96,6 +97,9 @@ type FileConfig struct {
 
 	// Skills section (see internal/skills package).
 	Skills *SkillsConfig `json:"skills,omitempty"`
+
+	// Memory section controls the persistent memory system.
+	Memory *memory.MemoryConfig `json:"memory,omitempty"`
 }
 
 // ResolvedConfig is the fully merged result. Every field has a concrete
@@ -158,6 +162,9 @@ type ResolvedConfig struct {
 
 	// Skills is the resolved skills config with default values.
 	Skills skills.SkillsConfig
+
+	// Memory is the resolved memory config with default values.
+	Memory memory.MemoryConfig
 }
 
 // ── Defaults ───────────────────────────────────────────────────────────
@@ -406,6 +413,7 @@ func LoadConfig(cli CLIFlags) ResolvedConfig {
 		SandboxVolumes: cfg.SandboxVolumes,
 		Skills:         resolveSkills(cfg.Skills),
 		Dangerous:      resolveDangerous(cfg.Dangerous),
+		Memory:         resolveMemory(cfg.Memory),
 	}
 
 	// Booleans: default to false if not set
@@ -486,6 +494,14 @@ func resolveDangerous(cfg *danger.DangerousConfig) danger.DangerousConfig {
 	return danger.DangerousConfig{}
 }
 
+// resolveMemory merges file-level memory config with defaults.
+func resolveMemory(cfg *memory.MemoryConfig) memory.MemoryConfig {
+	if cfg != nil {
+		return *cfg
+	}
+	return memory.DefaultMemoryConfig()
+}
+
 // overlayFile overlays a higher-priority FileConfig onto a lower-priority one.
 // Only fields that are explicitly set (non-zero for scalars, non-nil for
 // pointers) override the base value.

internal/memory/buffer.go

@@ -0,0 +1,81 @@
+package memory
+
+import (
+	"fmt"
+	"time"
+)
+
+// Buffer is a simple ring buffer for session-level turn summaries.
+// Thread-safe only if accessed from a single goroutine (the loop engine
+// owns the buffer and serializes all access).
+type Buffer struct {
+	lines []string
+	cap   int
+}
+
+// NewBuffer creates a ring buffer with the given capacity. cap=0 means
+// disabled (all appends are silently discarded).
+func NewBuffer(cap int) *Buffer {
+	if cap < 0 {
+		cap = 0
+	}
+	return &Buffer{
+		lines: make([]string, 0, cap),
+		cap:   cap,
+	}
+}
+
+// Append adds a line to the buffer. If the buffer is at capacity, the
+// oldest line is evicted first.
+func (b *Buffer) Append(line string) {
+	if b.cap <= 0 {
+		return
+	}
+	if len(b.lines) >= b.cap {
+		// Evict oldest
+		b.lines = b.lines[1:]
+	}
+	// Sanitize: strip newlines from the line
+	line = sanitizeLine(line)
+	b.lines = append(b.lines, line)
+}
+
+// Lines returns a copy of the current buffer contents (oldest first).
+func (b *Buffer) Lines() []string {
+	out := make([]string, len(b.lines))
+	copy(out, b.lines)
+	return out
+}
+
+// Clear removes all lines from the buffer.
+func (b *Buffer) Clear() {
+	b.lines = make([]string, 0, b.cap)
+}
+
+// Cap returns the maximum number of lines.
+func (b *Buffer) Cap() int { return b.cap }
+
+// Len returns the current number of lines.
+func (b *Buffer) Len() int { return len(b.lines) }
+
+// sanitizeLine removes newlines, tabs, and trims whitespace.
+func sanitizeLine(line string) string {
+	// Remove newlines and tabs
+	result := make([]byte, 0, len(line))
+	for i := 0; i < len(line); i++ {
+		c := line[i]
+		if c == '\n' || c == '\r' || c == '\t' {
+			result = append(result, ' ')
+		} else {
+			result = append(result, c)
+		}
+	}
+	return fmt.Sprintf("%s", string(result))
+}
+
+// FormatBufferLine creates a timestamped buffer line.
+// Format: "HH:MM  role  message"
+func FormatBufferLine(role, message string) string {
+	now := time.Now().UTC().Format("15:04")
+	return fmt.Sprintf("%s  %s  %s", now, role, message)
+}