@superbased/observer 1.6.28 → 1.7.0

package/README.md

@@ -599,28 +599,47 @@ importance score (for drops).
 
 ### Tuning
 
-`observer config` settings (in `~/.observer/config.toml`):
+`observer config` settings (in `~/.observer/config.toml`). These are the only
+keys the conversation compressor reads:
 
 ```toml
 [compression.conversation]
 enabled = true
+mode = "cache_aware"       # "token" | "cache" | "cache_aware" — default cache_aware; see matrix below
 target_ratio = 0.85
-mode = "token"             # or "cache" — restricts drops to tail half
-preserve_last_n = 4
-prefix_bytes = 8192
-compress_types = ["json", "logs", "text"]   # add "code", "diff", "html" to opt in
-min_bytes_to_compress = 1024
-
-[compression.conversation.weights]
-recency = 0.4
-reference = 0.3
-density = 0.15
-role = 0.15
+preserve_last_n = 5        # never drop the most recent N messages
+compress_types = ["json", "logs", "code"]   # default; add "text", "diff", "html" to opt in
 ```
 
 High importance scores on dropped events (≥0.5) suggest the threshold
 is too aggressive — raise `target_ratio` (e.g. 0.9 or 0.95).
 
+### Choosing a mode: Anthropic vs Codex
+
+Per-type `tool_result` compression runs in every mode; `mode` only changes how
+messages are dropped and whether an Anthropic `cache_control` marker is injected.
+
+| `mode` | What it does | Claude Code (Anthropic) | Codex / OpenAI |
+|---|---|---|---|
+| `token` | Per-type compress, then drop lowest-scored messages to hit `target_ratio`. | ✅ Works. | ✅ Clearest choice for Codex/OpenAI. |
+| `cache` | Restrict drops to the tail half + inject a `cache_control` marker at the prefix boundary. | ✅ Anthropic-specific. | ⚠️ No effect beyond `token`. |
+| `cache_aware` *(default)* | Skip drops, narrow compression to `tool_result` blocks, no marker; keep history byte-stable across turns so Anthropic's prefix cache keeps hitting. | ✅ **Recommended for Anthropic Pro/Max** — and the shipped default. | ⚠️ No effect beyond `token`. |
+
+The shipped default is `cache_aware` (`token` is just the internal fallback when
+`mode` is empty). The cache modes exist for **Anthropic's content-hash prefix
+cache** (`cache_control` is an Anthropic Messages API concept). OpenAI/Codex
+prompt caching is **automatic and server-side** — nothing to mark or tune, so
+the proxy's OpenAI path is mode-agnostic (the default `cache_aware` behaves like
+`token` there). So: keep `cache_aware` for Claude Code; `mode = "token"` reads
+honestly for a Codex/OpenAI-only setup.
+
+Beyond the keys above, three opt-in sub-features have their own tables —
+`[compression.conversation.stash]` (Compressed-Content Retrieval),
+`[compression.conversation.rolling]` (rolling summarisation, with a per-provider
+summary model: `summary_model` for Anthropic, `openai_summary_model` for
+OpenAI/Codex), and `[compression.conversation.compaction]`. The full knob
+reference lives in `docs/compression-modes.md`.
+
 
 ## Cost and token math
 
@@ -808,19 +827,11 @@ listen_addr = "127.0.0.1"
 port = 8081
 
 [compression.conversation]
-enabled = true
+enabled = false            # opt-in; default off
+mode = "cache_aware"       # default; "token" | "cache" | "cache_aware" (see "Choosing a mode")
 target_ratio = 0.85
-mode = "token"
-preserve_last_n = 4
-prefix_bytes = 8192
-compress_types = ["json", "logs", "text"]
-min_bytes_to_compress = 1024
-
-[compression.conversation.weights]
-recency = 0.4
-reference = 0.3
-density = 0.15
-role = 0.15
+preserve_last_n = 5
+compress_types = ["json", "logs", "code"]   # default; add "text"/"diff"/"html" to opt in
 
 [compression.shell]
 enabled = true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superbased/observer",
-  "version": "1.6.28",
+  "version": "1.7.0",
   "description": "SuperBased Observer — capture, normalize, compress, and analyze AI coding tool activity across Claude Code, Codex, Cursor, Cline/Roo, and Copilot.",
   "keywords": [
     "ai",
@@ -36,11 +36,11 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@superbased/observer-linux-x64": "1.6.28",
-    "@superbased/observer-linux-arm64": "1.6.28",
-    "@superbased/observer-darwin-x64": "1.6.28",
-    "@superbased/observer-darwin-arm64": "1.6.28",
-    "@superbased/observer-win32-x64": "1.6.28"
+    "@superbased/observer-linux-x64": "1.7.0",
+    "@superbased/observer-linux-arm64": "1.7.0",
+    "@superbased/observer-darwin-x64": "1.7.0",
+    "@superbased/observer-darwin-arm64": "1.7.0",
+    "@superbased/observer-win32-x64": "1.7.0"
   },
   "scripts": {
     "test": "node bin/observer.js --version"