From 898e1efc39d74b810c94de7aa5addf244d78acf6 Mon Sep 17 00:00:00 2001 From: Tanisha Aberdeen <32620895+aliasunder@users.noreply.github.com> Date: Tue, 14 Jul 2026 21:56:03 -0400 Subject: [PATCH] fix: trim DOCKERHUB.md to stay under Docker Hub's 25KB limit Exclude How It Works, Hybrid Search, Memory, and Tasks prose sections from the generated DOCKERHUB.md. These are already covered by the feature bullet list which links to each section on GitHub. Brings the output from 25,288 bytes (truncated mid-table) to 19,983 bytes. Co-Authored-By: Claude Opus 4.6 (1M context) --- DOCKERHUB.md | 47 ---------------------------- scripts/generate-dockerhub-readme.ts | 4 +++ 2 files changed, 4 insertions(+), 47 deletions(-) diff --git a/DOCKERHUB.md b/DOCKERHUB.md index 0f7fe013..cfc96ccf 100644 --- a/DOCKERHUB.md +++ b/DOCKERHUB.md @@ -57,53 +57,6 @@ See the [full Quick Start guide](https://github.com/aliasunder/vault-cortex#quick-start) for local setup (2 minutes with Docker), remote deployment with Obsidian Sync, and MCP client configuration. -## How It Works - - -The search index is rebuildable derived state — FTS5 keyword tables rebuild on startup, vector embeddings persist across restarts with content-hash gating (only changed notes re-embed). A file watcher keeps both current, and queries fuse both signals via Reciprocal Rank Fusion. The sync service keeps the vault in sync with your Obsidian apps — it ships inside the same container in the `:remote` image variant (remote deployments only; the default `:latest` image is the MCP server alone). - -See [ARCHITECTURE.md](https://github.com/aliasunder/vault-cortex/blob/main/ARCHITECTURE.md) for the full design, auth flow diagrams, and component breakdown. - -## Hybrid Search - -Keyword search alone fails when your vocabulary doesn't match the vault's — "aspirations" won't find a note about "targets", "coworkers" won't surface your "references" file. In testing against a real vault, 30% of natural-language queries returned zero or tangential results with keywords alone. Hybrid search eliminated those misses — vectors bridge the vocabulary gap, and the reranker rescues intent-heavy queries where neither signal is strong on its own. - -Hybrid search combines three ranking signals via [Reciprocal Rank Fusion](https://github.com/aliasunder/vault-cortex/blob/main/ARCHITECTURE.md#hybrid-search-r8): - -- **Keywords** (FTS5) stay precise on exact terms, jargon, and property values -- **Vectors** (sqlite-vec) bridge the vocabulary gap by matching on meaning -- **Reranker** (cross-encoder) refines ordering by scoring each query-document pair jointly — rescues intent-heavy queries where keywords and vectors both miss - -All models run locally (~45MB total, no external API). Set `EMBEDDING_ENABLED=false` for keyword-only search, or `RERANK_MODE=none` to skip reranking for lower latency. - -See [ARCHITECTURE.md → Hybrid Search](https://github.com/aliasunder/vault-cortex/blob/main/ARCHITECTURE.md#hybrid-search-r8) for model details, blend weights, and the full pipeline breakdown. - -## Memory - -A memory layer that only grows is only useful if agents can retrieve the right entries without dumping everything into context. Once you have hundreds of dated entries across multiple files — preferences, principles, communication style, ongoing commitments — reading whole files wastes context on irrelevant material and buries the signal. The memory system is designed for targeted retrieval: agents accumulate knowledge over time and recall exactly what's relevant to the task at hand. - -The layer is a folder of plain Markdown files (default: `About Me/`) holding dated entries under topic headings — auto-created with starter templates on first run, grown by agents through `vault_update_memory`. Three properties make it work: - -- **Append-only** — entries are never overwritten; corrections arrive as new dated entries. The layer becomes a personal knowledge base that captures your current state _and_ the evolution behind it -- **Topic recall** — `vault_memory_recall` retrieves every relevant entry across all memory files at once, keyword- and semantically-matched, oldest first. Ask "what do I think about X?" and get the current take plus the dated history of how it developed — no need to read entire files or guess which file holds what -- **Grows without degrading** — capping results (`max_results`) drops the least-relevant entries, never a slice of the timeline. A memory layer with 500 entries serves a targeted query as well as one with 50 - -Files that describe what's current rather than what has been true (routines, active commitments) can declare `entry-policy: living` in frontmatter — their expired entries are prunable rather than preserved, keeping the current-state picture accurate. - -See [templates/memory](https://github.com/aliasunder/vault-cortex/tree/main/templates/memory/) for the file format, entry-policy convention, and starter templates. - -## Tasks - -Task metadata lives in plain markdown — scattered across files, encoded in emoji signifiers or inline fields, organized under Kanban headings. An agent answering "what's overdue?" would need to parse every file and understand your chosen format; completing a task on a Kanban board means knowing the board's lane structure, the date syntax, and which heading is the done lane. - -The task layer handles this so agents don't have to: - -- **Find** — filter by status, six date fields (due, scheduled, start, created, done, cancelled), priority, folder, or Kanban lane. Each result carries its lane, note path, heading, and line number — no follow-up reads needed to locate a task -- **Update** — complete, reprioritize, and move tasks between Kanban lanes in a single call. Marking a task done auto-detects the done lane and stamps the completion date; reversing it removes the date. All three changes can happen at once -- **Both formats** — whichever format you use, [Tasks plugin](https://publish.obsidian.md/tasks/) emoji signifiers or [Dataview](https://blacksmithgu.github.io/obsidian-dataview/) inline fields, the server reads both and writes in the format your Tasks plugin is configured for - -See [ARCHITECTURE.md → Tasks](https://github.com/aliasunder/vault-cortex/blob/main/ARCHITECTURE.md#tasks-r9) for the indexing model, date cascade sorting, and Kanban lane detection. - ## Tools | Category | Tool | Description | diff --git a/scripts/generate-dockerhub-readme.ts b/scripts/generate-dockerhub-readme.ts index 7dd56b29..7064ca69 100644 --- a/scripts/generate-dockerhub-readme.ts +++ b/scripts/generate-dockerhub-readme.ts @@ -46,6 +46,10 @@ const LICENSE_REPLACEMENT = [ const EXCLUDED_H2 = new Set([ "Quick Start", + "How It Works", + "Hybrid Search", + "Memory", + "Tasks", "Data Integrity", "Authentication", "Development",