fossel 1.1.0 → 1.2.0

package/README.md

@@ -20,7 +20,31 @@
    npx -y fossel
    ```
 
-4. In chat, just say *"remember this"* and Fossel handles the rest. See [Simple mode](#simple-mode-recommended) below.
+4. In chat, say:
+
+   ```
+   remember: [anything about this repo]
+   ```
+
+   Then ask:
+
+   ```
+   what does Fossel remember about [topic]?
+   ```
+
+5. **Verify it works** — paste this in your AI chat:
+
+   ```
+   remember: Fossel is working in this repo
+   ```
+
+   Then immediately ask:
+
+   ```
+   what does Fossel remember?
+   ```
+
+   You should see your memory returned.
 
 **Database path:** `~/.fossel/memory.db` (override with `FOSSEL_DB_PATH`).
 
@@ -76,17 +100,14 @@ Every original tool is still available for power users.
 
 | Tool | Purpose |
 |------|---------|
-| `remember` | Natural-language save with auto-type/tags/dedupe (preferred). |
-| `get_context` | Unified pinned + recent + FTS retrieval. |
-| `resolve_repo` | Show canonical key, aliases, detected git remote. |
-| `dedupe_repo` | Find or merge near-duplicate memories. |
-| `store_context` | Explicit save with `type` and `tags`. |
-| `get_repo_context` | Recent memories grouped by type (pinned first). |
-| `search_memory` | FTS search, optional repo filter. |
-| `summarize_repo_context` | Markdown brief for a repo. |
-| `pin_memory` / `unpin_memory` | Pin important items. |
-| `update_memory` | Partial update by numeric id. |
-| `delete_memory` | Delete by legacy string id. |
+| `remember` | Save a memory in natural language — auto-infers type, tags, and repo |
+| `get_context` | Retrieve relevant memories, pinned first then recent |
+| `search_memory` | FTS search across notes, optional repo filter |
+| `pin_memory` / `unpin_memory` | Pin important memories to always appear first |
+| `delete_memory` | Delete by id |
+| `update_memory` | Edit an existing memory by id |
+| `dedupe_repo` | Merge near-duplicate memories |
+| `summarize_repo_context` | Markdown summary — useful for PR descriptions |
 
 ### Memory types
 
@@ -169,10 +190,11 @@ Reports on:
 
 - canonical repo key for the workspace
 - sibling keys that look like the same repo (offers a fix)
-- exact-duplicate memory clusters (suggest `dedupe_repo`)
+- exact-duplicate memory clusters (suggests `fossel doctor --fix` or `dedupe_repo`)
+- memory notes that still mention deprecated repo keys
 - detected MCP config files
 
-Exits non-zero when issues are found so it can run in CI.
+Pass `--fix` to apply safe automated cleanup in one go: merge sibling repo keys, rewrite stale alias mentions, and remove exact-text duplicates. Without `--fix` it's read-only and exits non-zero on issues so it can run in CI.
 
 ---
 
@@ -185,7 +207,10 @@ Exits non-zero when issues are found so it can run in CI.
   "mcpServers": {
     "fossel": {
       "command": "npx",
-      "args": ["-y", "fossel"]
+      "args": ["-y", "fossel"],
+      "env": {
+        "FOSSEL_WORKSPACE": "${workspaceFolder}"
+      }
     }
   }
 }
@@ -198,12 +223,17 @@ Exits non-zero when issues are found so it can run in CI.
   "mcpServers": {
     "fossel": {
       "command": "npx",
-      "args": ["-y", "fossel"]
+      "args": ["-y", "fossel"],
+      "env": {
+        "FOSSEL_WORKSPACE": "/path/to/your/project"
+      }
     }
   }
 }
 ```
 
+`FOSSEL_WORKSPACE` pins Fossel to your project root. Without it, the server falls back to `process.cwd()`, which is occasionally wrong — Cursor and Claude Desktop sometimes spawn MCP servers from your home directory, which would silently route memories to the wrong repo. Cursor expands `${workspaceFolder}` automatically; Claude Desktop needs an absolute path.
+
 ---
 
 ## Development (from source)
@@ -222,10 +252,54 @@ npm run ci           # typecheck + tests + build + smoke
 ## Notes
 
 - **Local-first:** data stays on your machine.
-- **Search:** FTS5 (no `sqlite-vec` in v1).
+- **Search:** FTS5 keyword search by default. Optional **hybrid semantic search**
+  via `FOSSEL_EMBEDDINGS=1` (see below).
 - **`FOSSEL_DB_PATH`:** optional override for DB location (e.g. tests).
 - **Schema:** migrations live in `src/db/migrate.ts`; reference shape in `src/db/schema.sql`.
 
+## Hybrid semantic search (optional)
+
+By default Fossel retrieves memories with FTS5 keyword search. Keyword search
+misses paraphrases — a query like "how does authentication work?" won't match a
+note that says "JWT lives in localStorage" because they share no words.
+
+Set `FOSSEL_EMBEDDINGS=1` to enable **hybrid retrieval**: a local, dependency-free
+embedding is computed for every memory and fused with the keyword results
+(Reciprocal Rank Fusion). This adds semantic recall while keeping FTS5's exact-
+match precision for identifiers, file paths, and ticket numbers.
+
+```json
+{
+  "mcpServers": {
+    "fossel": {
+      "command": "npx",
+      "args": ["-y", "fossel"],
+      "env": {
+        "FOSSEL_WORKSPACE": "${workspaceFolder}",
+        "FOSSEL_EMBEDDINGS": "1"
+      }
+    }
+  }
+}
+```
+
+Properties:
+
+- **Zero install weight / fully offline.** The embedding is a deterministic
+  feature-hashing of token unigrams and bigrams — no model download, no native
+  dependency, no network. It runs instantly and keeps the local-first promise.
+- **Opt-in.** With the flag unset, Fossel behaves exactly as before: no vectors
+  are written and retrieval is FTS-only.
+- **Self-healing index.** Memories created before enabling the flag are embedded
+  on demand the first time the repo is searched.
+- **Pluggable.** `embedText` in `src/lib/embeddings.ts` is the single entry
+  point, so a stronger embedder (transformers.js, ONNX, or a remote model) can
+  be swapped in later without touching callers. Bump `EMBEDDING_VERSION` to
+  trigger automatic re-indexing of stale vectors.
+
+Vectors are stored in a `memory_embeddings` side table keyed by memory rowid and
+cleaned up via trigger when a memory is deleted.
+
 ## Community
 
 If Fossel saves you time, **[star the repo](https://github.com/7vignesh/fossel)** and **[open an issue](https://github.com/7vignesh/fossel/issues)** for bugs or ideas — that helps others discover it too.