Skip to content

Commit 46f26ab

Browse files
docs: update README for v0.9.0 and v0.9.1 features
- Add v0.9.0 memory intelligence features to Pipeline Modules section (conflict detection, task-relevance ranking, expiry/supersede, sensitivity) - Update Roadmap: mark OpenAPI as shipped, add all v0.9.0 issues - Add OpenAPI/Swagger UI note to API Endpoints section - Update Embedding Providers with CLI usage examples - Update memory API examples with auto_classify, boost_tags, expire, supersede - Add conflict_threshold to config examples - Add docs/ link to Links section - Update Integrations with Ollama and Cohere Co-authored-by: Ona <no-reply@ona.com>
1 parent 0d60bcd commit 46f26ab

1 file changed

Lines changed: 53 additions & 10 deletions

File tree

README.md

Lines changed: 53 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -252,18 +252,28 @@ distill memory stats
252252
# Start API with memory enabled
253253
distill api --port 8080 --memory
254254

255-
# Store
255+
# Store (with auto sensitivity classification)
256256
curl -X POST http://localhost:8080/v1/memory/store \
257257
-H "Content-Type: application/json" \
258258
-d '{
259259
"session_id": "session-1",
260-
"entries": [{"text": "Auth uses JWT with RS256", "tags": ["auth"], "source": "docs"}]
260+
"entries": [{"text": "Auth uses JWT with RS256", "tags": ["auth"], "source": "docs", "auto_classify": true}]
261261
}'
262262

263-
# Recall
263+
# Recall (with task-relevance boosting)
264264
curl -X POST http://localhost:8080/v1/memory/recall \
265265
-H "Content-Type: application/json" \
266-
-d '{"query": "How does auth work?", "max_results": 5}'
266+
-d '{"query": "How does auth work?", "max_results": 5, "boost_tags": ["auth"], "min_relevance": 0.3}'
267+
268+
# Expire a memory (soft delete)
269+
curl -X POST http://localhost:8080/v1/memory/expire \
270+
-H "Content-Type: application/json" \
271+
-d '{"id": "memory-id"}'
272+
273+
# Supersede with a newer version
274+
curl -X POST http://localhost:8080/v1/memory/supersede \
275+
-H "Content-Type: application/json" \
276+
-d '{"id": "old-memory-id", "new_id": "new-memory-id"}'
267277
```
268278

269279
### MCP
@@ -285,12 +295,13 @@ Full text → Summary (~20%) → Keywords (~5%) → Evicted
285295
(24h) (7 days) (30 days)
286296
```
287297

288-
Accessing a memory resets its decay clock. Configure ages via `distill.yaml`:
298+
Accessing a memory resets its decay clock. Configure via `distill.yaml`:
289299

290300
```yaml
291301
memory:
292302
db_path: distill-memory.db
293303
dedup_threshold: 0.15
304+
conflict_threshold: 0.35
294305
```
295306
296307
## Session Management
@@ -414,6 +425,8 @@ distill completion powershell | Out-String | Invoke-Expression
414425

415426
## API Endpoints
416427

428+
Interactive docs available at `/docs` (Swagger UI). Full OpenAPI 3.1 spec at `/openapi.yaml`.
429+
417430
| Method | Path | Description |
418431
|--------|------|-------------|
419432
| POST | `/v1/dedupe` | Deduplicate chunks |
@@ -541,6 +554,7 @@ auth:
541554
memory:
542555
db_path: distill-memory.db
543556
dedup_threshold: 0.15
557+
conflict_threshold: 0.35
544558
545559
session:
546560
db_path: distill-sessions.db
@@ -600,7 +614,8 @@ If `DISTILL_API_KEYS` is not set, the API is open (suitable for local/internal u
600614

601615
**Alternatives:**
602616
- Bring your own embeddings - include `"embedding"` field in chunks
603-
- Self-host an embedding model - set `EMBEDDING_API_URL` to your endpoint
617+
- Use Ollama locally - `--embedding-provider ollama` (no API key needed)
618+
- Use Cohere - `--embedding-provider cohere` with `COHERE_API_KEY`
604619

605620
### Parameters
606621

@@ -787,7 +802,14 @@ Strategies can be chained via `compress.Pipeline`. Configure with target reducti
787802

788803
### Memory (`pkg/memory`)
789804

790-
Persistent context memory across agent sessions. SQLite-backed with write-time deduplication via cosine similarity. Memories decay over time: full text → summary → keywords → evicted. Recall ranked by `(1-w)*similarity + w*recency`. Enable with `--memory` flag.
805+
Persistent context memory across agent sessions. SQLite-backed with write-time deduplication via cosine similarity. Memories decay over time: full text → summary → keywords → evicted. Recall ranked by `(1-w)*similarity + w*recency` with optional task-relevance boosting. Enable with `--memory` flag.
806+
807+
**v0.9.0 additions:**
808+
809+
- **Conflict detection** — on store, entries with cosine distance 0.15–0.35 from existing memories are flagged as conflicts (contradictory information). Returned in `StoreResult.Conflicts`.
810+
- **Task-relevance ranking** — recall accepts `boost_tags`, `task_context`, and `min_relevance` to re-rank results by what matters for the current task.
811+
- **Expiry and supersession** — soft-delete via `POST /v1/memory/expire`, or replace with a newer version via `POST /v1/memory/supersede`. Expired entries are excluded from recall by default.
812+
- **Sensitivity classification** — automatic PII, credential, and internal-IP detection on store via `auto_classify: true`. Recall results include `max_sensitivity` and `sensitive_chunks` metadata.
791813

792814
#### Lifecycle events
793815

@@ -1012,7 +1034,20 @@ Pattern → annotation mapping:
10121034
10131035
## Embedding Providers
10141036
1015-
Distill supports multiple embedding backends via a unified factory. Import the provider package to register it, then call `embedding.NewProvider`:
1037+
Distill supports multiple embedding backends via a unified factory. Switch providers with `--embedding-provider` on any command:
1038+
1039+
```bash
1040+
# Use Ollama (local, no API key)
1041+
distill api --embedding-provider ollama --embedding-base-url http://localhost:11434
1042+
1043+
# Use Cohere
1044+
distill api --embedding-provider cohere
1045+
1046+
# Use OpenAI (default)
1047+
distill api --embedding-provider openai
1048+
```
1049+
1050+
Programmatically, import the provider package to register it, then call `embedding.NewProvider`:
10161051

10171052
```go
10181053
import (
@@ -1063,6 +1098,11 @@ Distill is evolving from a dedup utility into a context intelligence layer. Here
10631098
| **Per-call-site hit rate tracking** | [#47](https://github.com/Siddhant-K-code/distill/issues/47) | Shipped | `CallSiteTracker` records Anthropic cache usage per call site; `AllStats()` returns worst performers first. |
10641099
| **TTL-aware cache tracker** | [#49](https://github.com/Siddhant-K-code/distill/issues/49) | Shipped | `TTLTracker` monitors Anthropic's 5-minute cache TTL per prefix hash. `ScheduleDeadline` tells batch jobs the latest safe time to send the next request. |
10651100
| **Multi-provider embedding abstraction** | [#33](https://github.com/Siddhant-K-code/distill/issues/33) | Shipped | `embedding.NewProvider` factory supports OpenAI, Ollama, and Cohere via a unified `ProviderConfig`. Custom providers register via `RegisterFactory`. |
1101+
| **Memory expiry and supersession** | [#79](https://github.com/Siddhant-K-code/distill/issues/79) | Shipped | Soft-delete via `expire`, version replacement via `supersede`. Expired entries excluded from recall. |
1102+
| **Sensitivity classification** | [#82](https://github.com/Siddhant-K-code/distill/issues/82) | Shipped | Regex-based classifier detects PII, credentials, and internal IPs on store. Recall includes sensitivity metadata. |
1103+
| **Conflict detection** | [#77](https://github.com/Siddhant-K-code/distill/issues/77) | Shipped | Entries with cosine distance 0.15–0.35 from existing memories are flagged as conflicts on store. |
1104+
| **Task-relevance ranking** | [#78](https://github.com/Siddhant-K-code/distill/issues/78) | Shipped | Recall supports `boost_tags`, `task_context`, and `min_relevance` for task-aware re-ranking. |
1105+
| **Multi-provider embeddings (CLI)** | [#25](https://github.com/Siddhant-K-code/distill/issues/25) | Shipped | `--embedding-provider` flag on `api`, `serve`, and `memory` commands. Supports `openai`, `ollama`, `cohere`. |
10661106

10671107
### Code Intelligence
10681108

@@ -1082,8 +1122,9 @@ Distill is evolving from a dedup utility into a context intelligence layer. Here
10821122
| **Shell Completions** | [#26](https://github.com/Siddhant-K-code/distill/issues/26) | Shipped | `distill completion [bash\|zsh\|fish\|powershell]` generates shell completion scripts. |
10831123
| **Benchmark Suite** | [#24](https://github.com/Siddhant-K-code/distill/issues/24) | Shipped | `go test -bench=. ./...` covers cluster, MMR, selector, and compress with deterministic synthetic data. |
10841124
| **Makefile** | [#28](https://github.com/Siddhant-K-code/distill/issues/28) | Shipped | 20+ targets: build, test, bench, lint, fmt, vet, docker, release. |
1125+
| **OpenAPI Spec** | [#23](https://github.com/Siddhant-K-code/distill/issues/23) | Shipped | OpenAPI 3.1 spec at `/openapi.yaml`, Swagger UI at `/docs`. |
1126+
| **v2.0 Documentation** | [#8](https://github.com/Siddhant-K-code/distill/issues/8) | Shipped | Guides, API reference, configuration reference, LangChain and RAG examples. See [`docs/`](docs/). |
10851127
| **Python SDK** | [#5](https://github.com/Siddhant-K-code/distill/issues/5) | Planned | `pip install distill-ai` with LangChain/LlamaIndex integrations. |
1086-
| **OpenAPI Spec** | [#23](https://github.com/Siddhant-K-code/distill/issues/23) | Planned | Swagger UI at `/docs`, auto-generated client SDKs. |
10871128

10881129
See all open issues: [github.com/Siddhant-K-code/distill/issues](https://github.com/Siddhant-K-code/distill/issues)
10891130

@@ -1105,7 +1146,8 @@ Use LLMs for reasoning. Use deterministic algorithms for reliability.
11051146

11061147
Works with your existing AI stack:
11071148

1108-
- **LLM Providers:** OpenAI, Anthropic (more via [#33](https://github.com/Siddhant-K-code/distill/issues/33))
1149+
- **Embedding Providers:** OpenAI, Ollama (local), Cohere
1150+
- **LLM Providers:** OpenAI, Anthropic
11091151
- **Frameworks:** LangChain, LlamaIndex (SDKs planned: [#5](https://github.com/Siddhant-K-code/distill/issues/5))
11101152
- **Vector DBs:** Pinecone, Qdrant
11111153
- **AI Assistants:** Claude Desktop, Cursor (via MCP)
@@ -1182,6 +1224,7 @@ For commercial licensing, contact: siddhantkhare2694@gmail.com
11821224
- [Website](https://distill.siddhantkhare.com)
11831225
- [Playground](https://distill.siddhantkhare.com/playground)
11841226
- [The Agentic Engineering Guide](https://agents.siddhantkhare.com) - the book behind the concepts Distill implements
1227+
- [Documentation](docs/)
11851228
- [FAQ](FAQ.md)
11861229
- [Blog Post](https://dev.to/siddhantkcode/the-engineering-guide-to-context-window-efficiency-202b)
11871230
- [MCP Configuration](mcp/README.md)

0 commit comments

Comments
 (0)