docs: memory system docs + CI fix for subagent/security tests

- README.md: persistent memory feature section
- docs/CONFIG.md: memory config section
- docs/MEMORY.md: full design doc (already in previous commit)
- .github/workflows/test.yml: build binary before tests + KODE_BINARY env
- security_e2e_test.go: fix assertions for non-root CI environment

Author: jkyberneees

.github/workflows/test.yml

@@ -16,8 +16,11 @@ jobs:
         with:
           go-version: "1.24"
 
+      - name: build
+        run: go build -o /tmp/kode-test github.com/BackendStack21/kode/cmd/kode && chmod +x /tmp/kode-test
+
       - name: test
-        run: go test ./... -race -coverprofile=coverage.out -covermode=atomic -count=1
+        run: KODE_BINARY=/tmp/kode-test go test ./... -race -coverprofile=coverage.out -covermode=atomic -count=1
 
       - name: coverage
         run: go tool cover -func=coverage.out

README.md

@@ -22,6 +22,7 @@ kode run "Fix the OOM bug in default-hooks.js"
 - **Multi-turn** — `kode run --session` and `kode continue` for persistent conversations
 - **Configurable** — 4-layer config (global → project → env → CLI), `${VAR}` substitution
 - **Skills system** — On-demand knowledge through trigger‑matched SKILL.md files. Auto‑learn patterns with `--learn`. Import skills from URIs with LLM risk assessment.
+- **Persistent memory** — Three‑tier memory system (facts + session buffer + episode search). Agent‑managed via `memory` tool. Merge‑on‑write with go‑vector similarity detection saves ~80% LLM calls.
 
 ## Install
 
@@ -122,6 +123,24 @@ kode version                                    # Print version
 --no-agents            # Skip AGENTS.md
 ```
 
+## Features
+
+### Persistent Memory
+
+Three tiers managed automatically by the agent via the `memory` tool:
+
+| Tier | Storage | Cap | Managed by |
+|------|---------|-----|------------|
+| Facts | `~/.kode/memory/facts/{user,env}.md` | 1,500 + 2,500 chars | Agent via `memory` tool |
+| Buffer | In-session ring | 20 lines | Auto-appended each turn |
+| Episodes | `~/.kode/memory/episodes/<id>.md` | 1 KB each | LLM-extracted on session end |
+
+The agent can **add**, **replace**, **remove**, **consolidate**, **read**, or **search** memory using a single `memory` tool with six actions.
+
+**Merge-on-write** uses go-vector RandomProjections to detect duplicate entries before writing — cosine >0.7 auto-merges, <0.3 auto-adds, 0.3-0.7 asks the LLM. Saves ~80% of LLM calls.
+
+See [docs/MEMORY.md](docs/MEMORY.md) for the full design.
+
 ## Programmatic API
 
 ```go

cmd/kode/security_e2e_test.go

@@ -110,7 +110,11 @@ func TestSecurity_WriteFile_DestructivePath(t *testing.T) {
 
 func TestSecurity_WriteFile_CustomAllowlist(t *testing.T) {
 	// /etc is system_write → deny by default in deny-non-interactive mode.
-	// But an allowlist for this specific path should override.
+	// But non_interactive=allow should override the security denial.
+	// Note: the actual os.WriteFile may still fail due to filesystem
+	// permissions (we're not root in CI). That's OK — we're testing
+	// that the security layer allows the operation, not that the
+	// filesystem write succeeds.
 	allow := "allow"
 	dc := danger.DangerousConfig{
 		NonInteractive: &allow,
@@ -119,9 +123,10 @@ func TestSecurity_WriteFile_CustomAllowlist(t *testing.T) {
 	result := callJSON(t, tool, `{"path":"/etc/passwd","content":"hack"}`)
 	var r struct{ Error string `json:"error"` }
 	mustUnmarshal(t, result, &r)
-	// With non_interactive=allow, all operations are allowed
-	if r.Error != "" {
-		t.Errorf("expected allow with non_interactive=allow, got: %s", r.Error)
+	// With non_interactive=allow, the security layer should NOT issue
+	// a denial. A filesystem-level permission error is acceptable.
+	if strings.Contains(r.Error, "denied") {
+		t.Errorf("expected security layer to allow, got denial: %s", r.Error)
 	}
 }
 
@@ -354,7 +359,7 @@ func TestSecurity_ClassOverride_SystemWriteAllowed(t *testing.T) {
 	var r struct{ Error string `json:"error"` }
 	mustUnmarshal(t, result, &r)
 	// Write will fail because /etc is not writable, but it should NOT be a security denial
-	if r.Error != "" && strings.Contains(r.Error, "denied") {
+	if r.Error != "" && (strings.Contains(r.Error, "security") || strings.Contains(r.Error, "class")) {
 		t.Errorf("expected no security denial after system_write=allow, got: %s", r.Error)
 	}
 	// Error should be "cannot create directory" or similar FS error, not a config denial

docs/CONFIG.md

@@ -110,6 +110,34 @@ The `skills` section controls the skill system:
 | `curation.staleness_days` | — | 90 | Days without use before flagging as stale |
 | `curation.auto_prune` | — | false | Auto-delete stale skills on curate (no prompt) |
 
+## Memory configuration
+
+The `memory` section controls the persistent memory system (see [docs/MEMORY.md](docs/MEMORY.md)):
+
+```json
+{
+  "memory": {
+    "enabled": true,
+    "facts_limit_user": 1500,
+    "facts_limit_env": 2500,
+    "buffer_lines": 20,
+    "buffer_enabled": true,
+    "merge_on_write": true,
+    "extract_on_end": true
+  }
+}
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `enabled` | true | Enable memory system entirely |
+| `facts_limit_user` | 1500 | Max chars for `user.md` fact file |
+| `facts_limit_env` | 2500 | Max chars for `env.md` fact file |
+| `buffer_lines` | 20 | Max turn summaries in session buffer |
+| `buffer_enabled` | true | Enable the turn-level buffer |
+| `merge_on_write` | true | Use go-vector RP similarity to auto-merge related entries |
+| `extract_on_end` | true | Extract durable facts via LLM at session end (≥3 turns) |
+
 ## Sub-agent configuration
 
 The `subagent` section controls task decomposition and parallel sub-agent execution (see [docs/SUBAGENTS.md](docs/SUBAGENTS.md)):