Add TTL expiry for transient facts

README.md

@@ -17,7 +17,7 @@ OpenBrain is a Model Context Protocol (MCP) server that provides AI agents with
 
 | Tool | Description |
 |------|-------------|
-| `store` | Store a memory with automatic embedding generation and keyword extraction |
+| `store` | Store a memory with automatic embedding generation and optional TTL for transient facts |
 | `batch_store` | Store 1-50 memories atomically in a single call |
 | `query` | Search memories by semantic similarity |
 | `purge` | Delete memories by agent ID or time range |
@@ -86,6 +86,30 @@ OPENBRAIN_E2E_BASE_URL=https://ob.ingwaz.work
 OPENBRAIN__AUTH__ENABLED=true
 ```
 
+### TTL / Expiry
+
+Transient facts can be stored with an optional `ttl` string on `store`, or on
+either the batch itself or individual entries for `batch_store`.
+
+Supported units:
+
+- `s` seconds
+- `m` minutes
+- `h` hours
+- `d` days
+- `w` weeks
+
+Examples:
+
+- `30s`
+- `15m`
+- `1h`
+- `7d`
+
+Expired memories are filtered from `query` immediately, even before the
+background cleanup loop deletes them physically. The cleanup interval is
+configured with `OPENBRAIN__TTL__CLEANUP_INTERVAL_SECONDS` and defaults to 300.
+
 The CI workflow uses this remote mode after `main` deploys so e2e coverage validates the VPS deployment rather than the local runner host. It now generates a random per-run e2e key, temporarily appends it to the deployed `OPENBRAIN__AUTH__API_KEYS`, runs the suite, then removes the key and restarts the service.
 
 For live deployments, keep `OPENBRAIN__AUTH__API_KEYS` for persistent non-test access only. The server accepts a comma-separated key list, so a practical split is:
@@ -190,6 +214,7 @@ client runtime supports streamable HTTP. Codex should use `/mcp`.
     "arguments": {
       "content": "The user prefers dark mode and uses vim keybindings",
       "agent_id": "assistant-1",
+      "ttl": "7d",
       "metadata": {"source": "preferences"}
     }
   }
@@ -229,6 +254,7 @@ client runtime supports streamable HTTP. Codex should use `/mcp`.
       "entries": [
         {
           "content": "The user prefers dark mode",
+          "ttl": "24h",
           "metadata": {"category": "preference"}
         },
         {