fossel 1.0.8 → 1.1.0

package/README.md

@@ -1,105 +1,124 @@
 # Fossel
 
-Fossel is a local MCP (Model Context Protocol) memory server for open-source contributors. It stores project-specific context such as reviewer preferences, bug fixes, conventions, decisions, and issue notes in a local SQLite database with FTS5 search.
+**Local-first MCP memory for every repo you work on.** Store conventions, bug fixes, reviewer patterns, and decisions in **SQLite on your machine** (with FTS5 search). Works with **Cursor**, **Claude Desktop**, and any **stdio MCP** client. **No accounts, no cloud.**
 
-## Features
+---
 
-- Persistent local memory in SQLite (`~/.fossel/memory.db`)
-- Full-text search with SQLite FTS5
-- Repo-aware context retrieval grouped by memory type
-- Pinned memories that stay at the top of repo context
-- Structured markdown summaries for PR and planning context
-- Simple delete workflow by memory id
-- Partial memory updates by numeric id
-- CLI onboarding with `fossel init`
-- Local `stdio` MCP server for tools such as Cursor and Claude Desktop
+## Quick start (~2 minutes)
 
-## Memory Types
+1. **Onboard** (prints copy-paste MCP config + creates a sample memory):
 
-- `convention`
-- `bug_fix`
-- `reviewer_pattern`
-- `decision`
-- `issue`
-- `general`
+   ```bash
+   npx -y fossel init
+   ```
 
-## Install
+2. **Add the JSON** from the output to **Cursor** (`~/.cursor/mcp.json`) or **Claude Desktop** MCP settings, then restart the app.
 
-```bash
-npm install
-```
+3. **Run the server** (what the IDE launches; you can also run it manually for testing):
 
-Or run without installation:
+   ```bash
+   npx -y fossel
+   ```
 
-```bash
-npx -y fossel
-```
+4. In chat, just say *"remember this"* and Fossel handles the rest. See [Simple mode](#simple-mode-recommended) below.
 
-## Commands
+**Database path:** `~/.fossel/memory.db` (override with `FOSSEL_DB_PATH`).
 
-```bash
-npx -y fossel          # start MCP server over stdio
-npx -y fossel init     # onboarding for current repository
-```
+---
 
-## `fossel init`
+## Why Fossel?
 
-`fossel init` detects your current repo, prints ready-to-copy MCP config snippets for Cursor and Claude Desktop, inserts a starter memory, and shows DB stats plus command references.
+| You get | Details |
+|--------|---------|
+| **Local data** | SQLite + migrations; nothing leaves your disk unless you share it. |
+| **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. |
 
-Starter memory inserted:
+---
 
-- Type: `convention`
-- Content: `Fossel is active for this repo. Use store_context to save context.`
+## Simple mode (recommended)
 
-## MCP Tools
+Two tools cover the 80% case. Neither needs you to specify `type` or `tags`.
 
-- `store_context`: Save a new memory for a repository.
-- `get_repo_context`: Fetch recent memories for a repository, grouped by type. Pinned entries are always listed first and marked `📌 Pinned`.
-- `search_memory`: Full-text search memories across all repos or a single repo.
-- `delete_memory`: Delete a memory by id.
-- `update_memory`: Update memory content and/or type by numeric id.
-- `pin_memory`: Pin a memory by numeric id.
-- `unpin_memory`: Unpin a memory by numeric id.
-- `summarize_repo_context`: Return a structured markdown summary for a repo.
+### `remember` — save a memory
 
-## Tool Examples
+Just send a sentence. Fossel infers the memory type, generates tags, resolves the repo, and merges near-duplicates into the existing row.
 
-### `update_memory`
+> **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`.
 
-Input:
+### `get_context` — pull repo context
 
-```json
-{
-  "id": 12,
-  "content": "Use `pnpm` workspaces for all package scripts.",
-  "memory_type": "convention"
-}
-```
+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.
+
+That's it for daily use. The repo is detected from your `cwd` automatically.
+
+### Zero-prompt usage in Cursor
 
-### `pin_memory`
+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.
 
-Input:
+---
+
+## Advanced mode
+
+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. |
+
+### Memory types
+
+`convention`, `bug_fix`, `reviewer_pattern`, `decision`, `issue`, `general`.
+
+### Tool examples
+
+`store_context` (explicit form):
 
 ```json
 {
-  "id": 12
+  "repo": "7vignesh/fossel",
+  "type": "convention",
+  "note": "Use pnpm workspaces for all package scripts.",
+  "tags": ["pnpm", "workspaces"]
 }
 ```
 
-### `summarize_repo_context`
-
-Input:
+`pin_memory`:
 
 ```json
-{
-  "repo": "RocketChat"
-}
+{ "id": 12 }
 ```
 
-Output format:
+`summarize_repo_context`:
+
+```json
+{ "repo": "RocketChat/Rocket.Chat" }
+```
 
 ```md
-Fossel Context Summary: RocketChat
+Fossel Context Summary: RocketChat/Rocket.Chat
 
 📌 Pinned
 - (12) Always run test matrix before merge.
@@ -111,9 +130,55 @@ Bug Fixes
 - (5) Fixed webhook retries by making queue idempotent.
 ```
 
-## Cursor MCP Config
+`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`
 
-Add this to your Cursor MCP configuration:
+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`)
+- detected MCP config files
+
+Exits non-zero when issues are found so it can run in CI.
+
+---
+
+## Cursor MCP config
+
+`~/.cursor/mcp.json`:
 
 ```json
 {
@@ -126,9 +191,7 @@ Add this to your Cursor MCP configuration:
 }
 ```
 
-## Claude Desktop MCP Config
-
-Add this to your Claude Desktop MCP config:
+## Claude Desktop MCP config
 
 ```json
 {
@@ -141,29 +204,28 @@ Add this to your Claude Desktop MCP config:
 }
 ```
 
-## Development
+---
 
-```bash
-npm run dev
-```
-
-This starts the local MCP server over stdio.
-
-## Build
+## 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 + tests + build + smoke
 ```
 
-## Run Built Server
+## Notes
 
-```bash
-npm run start
-```
+- **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`; reference shape in `src/db/schema.sql`.
 
-## Notes
+## Community
 
-- Fossel is local-first: data remains on your machine.
-- FTS5 is used for V1 search (no `sqlite-vec`).
-- Optional: set `FOSSEL_DB_PATH` to override the default database path for testing.
-- DB schema changes are managed via startup migrations in `src/db/migrate.ts`.
+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.