docs: add session and memory docs across all doc files

- CHANGELOG: add [Unreleased] section with session management
- FAQ: add memory, session, and MCP tools Q&As; update roadmap status
- examples/session_api.sh: full API usage example
- mcp/README: add memory + session tool docs, config examples,
  integration patterns (session tracking, cross-session memory)
- mcp/claude_desktop_config_full.example.json: config with all features

Co-authored-by: Ona <no-reply@ona.com>

Author: Siddhant-K-code

CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to Distill are documented here.
 
+## [Unreleased]
+
+### Added
+
+- **Session-based context window management** (`pkg/session`) — Token-budgeted context windows for long-running agent sessions. Entries are deduplicated on push, compressed through hierarchical levels (full text → summary → sentence → keywords), and evicted when the budget is exceeded. Lowest-importance entries are compressed first. ([#38](https://github.com/Siddhant-K-code/distill/pull/38), closes [#31](https://github.com/Siddhant-K-code/distill/issues/31))
+- **Session CLI** — `distill session create/push/context/delete` commands. ([#38](https://github.com/Siddhant-K-code/distill/pull/38))
+- **Session HTTP API** — `/v1/session/create`, `/push`, `/context`, `/delete`, `/get` endpoints. Opt-in via `--session` flag. ([#38](https://github.com/Siddhant-K-code/distill/pull/38))
+- **Session MCP tools** — `create_session`, `push_session`, `session_context`, `delete_session` for Claude Desktop, Cursor, and Amp. Opt-in via `--session` flag. ([#38](https://github.com/Siddhant-K-code/distill/pull/38))
+
+### Stats
+
+- 9 files changed, 1,928 insertions, 6 deletions
+- 1 new package: `pkg/session`
+- 13 new tests
+
+---
+
 ## [v0.3.0] - 2026-02-23
 
 Feature release adding persistent context memory, SSE streaming, OpenTelemetry tracing, and project documentation.

FAQ.md

@@ -20,6 +20,18 @@ LLMs are non-deterministic. The same input can produce different compressed outp
 
 ---
 
+### What is Context Memory?
+
+Persistent memory that accumulates knowledge across agent sessions. Store context once, recall it later by semantic similarity + recency. Memories are deduplicated on write and compressed over time through hierarchical decay (full text → summary → keywords → evicted). Enable with `--memory` on the `api` or `mcp` commands.
+
+### What are Sessions?
+
+Token-budgeted context windows for long-running agent tasks. Push context incrementally as the agent works - Distill deduplicates entries, compresses aging ones, and evicts when the budget is exceeded. The `preserve_recent` setting keeps the N most recent entries at full fidelity. Enable with `--session` on the `api` or `mcp` commands.
+
+### How is Context Memory different from Sessions?
+
+Memory is cross-session: knowledge persists after a session ends and can be recalled in future sessions. Sessions are within-task: a bounded context window that tracks what the agent has seen during a single task, enforcing a token budget. Use memory for long-term knowledge, sessions for working context.
+
 ## Algorithms
 
 ### Why agglomerative clustering instead of K-Means?
@@ -108,6 +120,10 @@ Yes. The HTTP API is framework-agnostic. MCP works with any MCP-compatible clien
 
 LangChain's `search_type="mmr"` applies MMR at the vector DB level - a single re-ranking step. Distill runs a multi-stage pipeline: cache lookup, agglomerative clustering (groups similar chunks), representative selection (picks the best from each group), compression (reduces token count), then MMR (diversity re-ranking). The clustering step is the key difference - it understands group structure, not just pairwise similarity.
 
+### What MCP tools does Distill expose?
+
+The base MCP server exposes `deduplicate_context` and `analyze_redundancy`. With `--memory`, it adds `store_memory`, `recall_memory`, `forget_memory`, `memory_stats`. With `--session`, it adds `create_session`, `push_session`, `session_context`, `delete_session`. Enable both with `distill mcp --memory --session`.
+
 ### Can I use Distill with local models (Ollama, vLLM)?
 
 The dedup pipeline itself doesn't call any LLM - it's pure math (cosine distance, clustering). The only external dependency is for embedding generation when you send text without pre-computed embeddings. Multi-provider embedding support (Ollama, Azure, Cohere, HuggingFace) is planned in [#33](https://github.com/Siddhant-K-code/distill/issues/33).
@@ -180,8 +196,10 @@ Yes, AGPL-3.0. The full pipeline, CLI, API server, MCP server, and all algorithm
 
 ### What's on the roadmap?
 
-Three pillars:
+**Shipped:**
+- **Context Memory** - Persistent deduplicated memory across sessions with hierarchical decay ([#29](https://github.com/Siddhant-K-code/distill/issues/29))
+- **Session Management** - Token-budgeted context windows with compression and eviction ([#31](https://github.com/Siddhant-K-code/distill/issues/31))
 
-1. **Context Memory** - Persistent deduplicated memory across agent sessions with hierarchical decay ([#29](https://github.com/Siddhant-K-code/distill/issues/29), [#31](https://github.com/Siddhant-K-code/distill/issues/31))
-2. **Code Intelligence** - Dependency graphs, co-change patterns, blast radius analysis ([#30](https://github.com/Siddhant-K-code/distill/issues/30), [#32](https://github.com/Siddhant-K-code/distill/issues/32))
-3. **Platform** - Python SDK, multi-provider embeddings, batch API ([#5](https://github.com/Siddhant-K-code/distill/issues/5), [#33](https://github.com/Siddhant-K-code/distill/issues/33), [#11](https://github.com/Siddhant-K-code/distill/issues/11))
+**Upcoming:**
+1. **Code Intelligence** - Dependency graphs, co-change patterns, blast radius analysis ([#30](https://github.com/Siddhant-K-code/distill/issues/30), [#32](https://github.com/Siddhant-K-code/distill/issues/32))
+2. **Platform** - Python SDK, multi-provider embeddings, batch API ([#5](https://github.com/Siddhant-K-code/distill/issues/5), [#33](https://github.com/Siddhant-K-code/distill/issues/33), [#11](https://github.com/Siddhant-K-code/distill/issues/11))

examples/session_api.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+# Example: Session-based context window management via the API
+#
+# Start the server (in another terminal):
+#   distill api --port 8080 --session
+#
+# Sessions track context for long-running agent tasks with a token budget.
+# Entries are deduplicated on push, compressed as they age, and evicted
+# when the budget is exceeded.
+
+BASE="http://localhost:8080"
+
+echo "=== Create session ==="
+curl -s -X POST "$BASE/v1/session/create" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "session_id": "demo-task",
+    "max_tokens": 50000
+  }' | jq .
+
+echo ""
+echo "=== Push context entries ==="
+curl -s -X POST "$BASE/v1/session/push" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "session_id": "demo-task",
+    "entries": [
+      {
+        "role": "user",
+        "content": "Fix the JWT validation bug in the auth service",
+        "importance": 1.0
+      },
+      {
+        "role": "tool",
+        "content": "File: auth/jwt.go\n\npackage auth\n\nimport (\n\t\"crypto/rsa\"\n\t\"time\"\n)\n\nfunc ValidateToken(token string, key *rsa.PublicKey) error {\n\t// BUG: not checking expiry\n\treturn nil\n}",
+        "source": "file_read",
+        "importance": 0.8
+      },
+      {
+        "role": "tool",
+        "content": "File: auth/jwt_test.go\n\npackage auth\n\nimport \"testing\"\n\nfunc TestValidateToken(t *testing.T) {\n\t// No expiry test\n}",
+        "source": "file_read",
+        "importance": 0.6
+      },
+      {
+        "role": "assistant",
+        "content": "The ValidateToken function is missing expiry checks. I will add time.Now().After(claims.ExpiresAt) validation.",
+        "importance": 0.9
+      }
+    ]
+  }' | jq .
+
+echo ""
+echo "=== Read context window ==="
+curl -s -X POST "$BASE/v1/session/context" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "session_id": "demo-task"
+  }' | jq .
+
+echo ""
+echo "=== Read only tool entries ==="
+curl -s -X POST "$BASE/v1/session/context" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "session_id": "demo-task",
+    "role": "tool"
+  }' | jq .
+
+echo ""
+echo "=== Get session metadata ==="
+curl -s "$BASE/v1/session/get?session_id=demo-task" | jq .
+
+echo ""
+echo "=== Clean up ==="
+curl -s -X DELETE "$BASE/v1/session/delete" \
+  -H "Content-Type: application/json" \
+  -d '{"session_id": "demo-task"}' | jq .

mcp/README.md

@@ -24,8 +24,11 @@ It clusters semantically similar chunks, picks the best representative from each
 # Build
 go build -o distill .
 
-# Start MCP server
+# Start MCP server (dedup only)
 ./distill mcp
+
+# With memory and sessions enabled
+./distill mcp --memory --session
 ```
 
 ### Remote (HTTP) - Hosted deployment
@@ -34,6 +37,9 @@ go build -o distill .
 # Start HTTP server
 ./distill mcp --transport http --port 8081
 
+# With all features
+./distill mcp --transport http --port 8081 --memory --session
+
 # Or deploy to Fly.io
 fly deploy -c fly.mcp.toml
 ```
@@ -74,6 +80,78 @@ Query a vector database with automatic deduplication. Requires `--backend` flag.
 
 Analyze chunks for redundancy without removing any. Use to understand overlap before deduplicating.
 
+### `store_memory` (requires `--memory`)
+
+Store context that should persist across sessions. Memories are deduplicated on write.
+
+```json
+{
+  "text": "Auth service uses JWT with RS256 signing",
+  "tags": ["auth", "jwt"],
+  "source": "code_review"
+}
+```
+
+### `recall_memory` (requires `--memory`)
+
+Recall relevant memories by semantic similarity + recency.
+
+```json
+{
+  "query": "How does authentication work?",
+  "max_results": 5,
+  "tags": ["auth"]
+}
+```
+
+### `forget_memory` (requires `--memory`)
+
+Remove memories by tag or age.
+
+### `memory_stats` (requires `--memory`)
+
+Get memory store statistics (total count, by decay level, by source).
+
+### `create_session` (requires `--session`)
+
+Create a token-budgeted context window for a task.
+
+```json
+{
+  "session_id": "fix-auth-bug",
+  "max_tokens": 128000
+}
+```
+
+### `push_session` (requires `--session`)
+
+Push context entries to a session. Entries are deduplicated and the token budget is enforced via compression and eviction.
+
+```json
+{
+  "session_id": "fix-auth-bug",
+  "content": "File: auth/jwt.go\n...",
+  "role": "tool",
+  "source": "file_read",
+  "importance": 0.8
+}
+```
+
+### `session_context` (requires `--session`)
+
+Read the current context window. Returns entries in push order with compression levels and token counts.
+
+```json
+{
+  "session_id": "fix-auth-bug",
+  "max_tokens": 50000
+}
+```
+
+### `delete_session` (requires `--session`)
+
+Delete a session and all its entries.
+
 ## Resources
 
 ### `distill://system-prompt`
@@ -102,7 +180,7 @@ Arguments:
 
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
-**Local (stdio):**
+**Local (stdio) - dedup only:**
 ```json
 {
   "mcpServers": {
@@ -114,6 +192,21 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
+**With memory and sessions:**
+```json
+{
+  "mcpServers": {
+    "distill": {
+      "command": "/path/to/distill",
+      "args": ["mcp", "--memory", "--session"],
+      "env": {
+        "OPENAI_API_KEY": "your-openai-key"
+      }
+    }
+  }
+}
+```
+
 **Remote (HTTP):**
 ```json
 {
@@ -131,7 +224,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
   "mcpServers": {
     "distill": {
       "command": "/path/to/distill",
-      "args": ["mcp", "--backend", "pinecone", "--index", "my-index"],
+      "args": ["mcp", "--backend", "pinecone", "--index", "my-index", "--memory", "--session"],
       "env": {
         "PINECONE_API_KEY": "your-api-key",
         "OPENAI_API_KEY": "your-openai-key"
@@ -219,7 +312,30 @@ AI: [calls analyze_redundancy]
 AI: "Found 40% redundancy across 3 clusters. Want me to deduplicate?"
 ```
 
-### Pattern 4: Direct Vector DB Query
+### Pattern 4: Session-Based Context Tracking
+
+Track context across a multi-step task:
+
+```
+1. AI creates a session: create_session("fix-auth-bug", 128000)
+2. AI reads files: push_session(role="tool", content=file, source="file_read")
+3. AI reads tests: push_session(role="tool", content=tests, source="file_read")
+4. Budget exceeded → oldest low-importance entries compressed automatically
+5. AI reads context: session_context() → deduplicated, budget-aware window
+6. Task done: delete_session()
+```
+
+### Pattern 5: Cross-Session Memory
+
+Persist knowledge that should survive across sessions:
+
+```
+1. AI discovers a pattern: store_memory("Auth uses JWT with RS256", tags=["auth"])
+2. Next session, different task: recall_memory("How does auth work?")
+3. AI gets relevant memories without re-reading files
+```
+
+### Pattern 6: Direct Vector DB Query
 
 If backend is configured, query with automatic deduplication:
 

mcp/claude_desktop_config_full.example.json

@@ -0,0 +1,18 @@
+{
+  "mcpServers": {
+    "distill": {
+      "command": "/path/to/distill",
+      "args": [
+        "mcp",
+        "--memory",
+        "--session",
+        "--backend", "pinecone",
+        "--index", "your-index-name"
+      ],
+      "env": {
+        "PINECONE_API_KEY": "your-pinecone-api-key",
+        "OPENAI_API_KEY": "your-openai-api-key"
+      }
+    }
+  }
+}