fossel 1.0.9 → 1.1.1

package/README.md

@@ -14,13 +14,13 @@
 
 2. **Add the JSON** from the output to **Cursor** (`~/.cursor/mcp.json`) or **Claude Desktop** MCP settings, then restart the app.
 
-3. **Run the server** (what the IDE launches, or for testing):
+3. **Run the server** (what the IDE launches; you can also run it manually for testing):
 
    ```bash
    npx -y fossel
    ```
 
-4. In chat, use tools like `store_context` and `get_repo_context` with your **repo** name (e.g. `org/repo` or your folder name).
+4. In chat, just say *"remember this"* and Fossel handles the rest. See [Simple mode](#simple-mode-recommended) below.
 
 **Database path:** `~/.fossel/memory.db` (override with `FOSSEL_DB_PATH`).
 
@@ -31,78 +31,94 @@
 | You get | Details |
 |--------|---------|
 | **Local data** | SQLite + migrations; nothing leaves your disk unless you share it. |
-| **Repo-scoped memory** | Same patterns across Cursor, Claude, or any MCP client over stdio. |
+| **Repo-scoped memory** | One canonical key per repo; aliases collapse automatically. |
 | **Find anything** | FTS5 search across notes; pin what matters; summarize for PRs. |
+| **Ambient capture** | Natural-language `remember`; dedupes near-duplicates on save. |
 | **Evolving schema** | Startup migrations keep upgrades safe for existing databases. |
 
 ---
 
-## Features
+## Simple mode (recommended)
 
-- Persistent memory in SQLite (`~/.fossel/memory.db`)
-- Full-text search (FTS5)
-- Repo-aware context, grouped by memory type
-- Pinned memories at the top of `get_repo_context`
-- `summarize_repo_context` for markdown briefs (PRs, planning)
-- `update_memory`, `pin_memory`, `unpin_memory`
-- CLI: `fossel init` for onboarding
-- `stdio` MCP server for Cursor, Claude Desktop, and compatible tools
+Two tools cover the 80% case. Neither needs you to specify `type` or `tags`.
 
-## Memory types
+### `remember` — save a memory
 
-- `convention`, `bug_fix`, `reviewer_pattern`, `decision`, `issue`, `general`
+Just send a sentence. Fossel infers the memory type, generates tags, resolves the repo, and merges near-duplicates into the existing row.
 
-## Commands
+> **You:** Remember: JWT lives in localStorage and 401 redirects to /login.
+>
+> **Agent calls** `remember({ note: "JWT lives in localStorage and 401 redirects to /login." })`
+>
+> **Fossel:** Stored as `convention` with tags `jwt, auth, login` for `7vignesh/fossel`.
 
-```bash
-npx -y fossel          # MCP server over stdio
-npx -y fossel init     # onboarding + config snippets + sample memory
-```
+### `get_context` — pull repo context
+
+Pinned first, then recent, then FTS matches if you pass a `query`. Default limit of 8 is tuned for LLM context injection.
+
+> **You:** What does Fossel remember about auth here?
+>
+> **Agent calls** `get_context({ query: "auth" })`
+>
+> **Fossel:** returns a markdown block ready to drop into the system prompt.
 
-## `fossel init`
+That's it for daily use. The repo is detected from your `cwd` automatically.
 
-Detects the current git repo (or folder name), prints **Cursor** and **Claude Desktop** MCP snippets, inserts a starter **convention** memory (`Fossel is active for this repo…`), and shows DB path + memory count.
+### Zero-prompt usage in Cursor
 
-## MCP tools
+Fossel exposes a static MCP resource at `fossel://context/current-repo`. Cursor and Claude Desktop list resources on session start, so Fossel's pinned + recent memories show up before you type anything. Clients that don't list resources can still call `get_context` from the agent's first turn — that's all the prompting needed.
+
+---
+
+## Advanced mode
+
+Every original tool is still available for power users.
 
 | Tool | Purpose |
 |------|---------|
-| `store_context` | Save memory for a repo |
-| `get_repo_context` | Recent memories by type (pinned first) |
-| `search_memory` | FTS search, optional repo filter |
-| `delete_memory` | Delete by legacy string id |
-| `update_memory` | Partial update by numeric id |
-| `pin_memory` / `unpin_memory` | Pin important items |
-| `summarize_repo_context` | Markdown summary for a repo |
+| `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. |
+
+### Memory types
 
-## Tool examples
+`convention`, `bug_fix`, `reviewer_pattern`, `decision`, `issue`, `general`.
 
-### `update_memory`
+### Tool examples
+
+`store_context` (explicit form):
 
 ```json
 {
-  "id": 12,
-  "content": "Use `pnpm` workspaces for all package scripts.",
-  "memory_type": "convention"
+  "repo": "7vignesh/fossel",
+  "type": "convention",
+  "note": "Use pnpm workspaces for all package scripts.",
+  "tags": ["pnpm", "workspaces"]
 }
 ```
 
-### `pin_memory`
+`pin_memory`:
 
 ```json
 { "id": 12 }
 ```
 
-### `summarize_repo_context`
+`summarize_repo_context`:
 
 ```json
-{ "repo": "RocketChat" }
+{ "repo": "RocketChat/Rocket.Chat" }
 ```
 
-Example output shape:
-
 ```md
-Fossel Context Summary: RocketChat
+Fossel Context Summary: RocketChat/Rocket.Chat
 
 📌 Pinned
 - (12) Always run test matrix before merge.
@@ -114,6 +130,57 @@ Bug Fixes
 - (5) Fixed webhook retries by making queue idempotent.
 ```
 
+`dedupe_repo` (dry run, then apply):
+
+```json
+{ "repo": "7vignesh/fossel", "apply": false }
+{ "repo": "7vignesh/fossel", "apply": true, "threshold": 0.85 }
+```
+
+---
+
+## Repo identity
+
+Fossel resolves the canonical key for your workspace in this order:
+
+1. `git remote get-url origin` → normalized to `owner/repo`
+2. folder basename
+3. anything you pass explicitly is recorded as an alias of the above
+
+Memories saved under any alias are reachable from the canonical key, and `npx fossel init` automatically merges legacy alias rows (e.g. `studentmanager` → `7vignesh/student-manager`).
+
+---
+
+## Commands
+
+```bash
+npx -y fossel          # MCP server over stdio
+npx -y fossel init     # onboarding + canonical key + safe alias merge
+npx -y fossel doctor   # diagnose repo sprawl, duplicates, MCP config
+```
+
+### `fossel init`
+
+Detects the canonical repo key, prints **Cursor** and **Claude Desktop** MCP snippets, merges legacy alias rows into the canonical key, and inserts a starter memory only when the database is empty.
+
+### `fossel doctor`
+
+Reports on:
+
+- canonical repo key for the workspace
+- sibling keys that look like the same repo (offers a fix)
+- exact-duplicate memory clusters (suggests `fossel doctor --fix` or `dedupe_repo`)
+- memory notes that still mention deprecated repo keys
+- detected MCP config files
+
+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.
+
+### `fossel init`
+
+`fossel init` auto-deduplicates exact duplicate memories at the end of the run; pass `--no-dedupe` to opt out.
+
+---
+
 ## Cursor MCP config
 
 `~/.cursor/mcp.json`:
@@ -123,7 +190,10 @@ Bug Fixes
   "mcpServers": {
     "fossel": {
       "command": "npx",
-      "args": ["-y", "fossel"]
+      "args": ["-y", "fossel"],
+      "env": {
+        "FOSSEL_WORKSPACE": "${workspaceFolder}"
+      }
     }
   }
 }
@@ -136,20 +206,30 @@ Bug Fixes
   "mcpServers": {
     "fossel": {
       "command": "npx",
-      "args": ["-y", "fossel"]
+      "args": ["-y", "fossel"],
+      "env": {
+        "FOSSEL_WORKSPACE": "/absolute/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)
 
 ```bash
 npm install
 npm run dev          # MCP server over stdio
+npm run typecheck
+npm test             # unit tests (node:test via tsx)
+npm run smoke        # end-to-end MCP roundtrip
 npm run build
 npm run start        # node dist/index.js
-npm run ci           # typecheck + build + smoke
+npm run ci           # typecheck + tests + build + smoke
 ```
 
 ## Notes
@@ -157,8 +237,8 @@ npm run ci           # typecheck + build + smoke
 - **Local-first:** data stays on your machine.
 - **Search:** FTS5 (no `sqlite-vec` in v1).
 - **`FOSSEL_DB_PATH`:** optional override for DB location (e.g. tests).
-- **Schema:** migrations live in `src/db/migrate.ts`.
+- **Schema:** migrations live in `src/db/migrate.ts`; reference shape in `src/db/schema.sql`.
 
 ## 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.
+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.