fossel 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vignesh Gopikrishnan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# Fossyl
+
+Fossyl 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.
+
+## Features
+
+- Persistent local memory in SQLite (`~/.fossyl/memory.db`)
+- Full-text search with SQLite FTS5
+- Repo-aware context retrieval grouped by memory type
+- Simple delete workflow by memory id
+- Local `stdio` MCP server for tools such as Cursor and Claude Desktop
+
+## Memory Types
+
+- `convention`
+- `bug_fix`
+- `reviewer_pattern`
+- `decision`
+- `issue`
+- `general`
+
+## Install
+
+```bash
+npm install
+```
+
+## Development
+
+```bash
+npm run dev
+```
+
+This starts the local MCP server over stdio.
+
+## Build
+
+```bash
+npm run build
+```
+
+## Run Built Server
+
+```bash
+npm run start
+```
+
+## MCP Tools
+
+- `store_context`: Save a new memory for a repository.
+- `get_repo_context`: Fetch recent memories for a repository, grouped by type.
+- `search_memory`: Full-text search memories across all repos or a single repo.
+- `delete_memory`: Delete a memory by id.
+
+## Cursor MCP Config
+
+Add this to your Cursor MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "fossel": {
+      "command": "npx",
+      "args": ["-y", "fossel"]
+    }
+  }
+}
+```
+
+## Notes
+
+- Fossyl is local-first: data remains on your machine.
+- FTS5 is used for V1 search (no `sqlite-vec`).
+- Optional: set `FOSSYL_DB_PATH` to override the default database path for testing.

package/dist/index.js

@@ -0,0 +1,388 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { homedir } from "os";
+import { join } from "path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/db/client.ts
+import Database from "better-sqlite3";
+import { mkdirSync } from "fs";
+import { dirname } from "path";
+var MEMORY_TYPES = [
+  "convention",
+  "bug_fix",
+  "reviewer_pattern",
+  "decision",
+  "issue",
+  "general"
+];
+var dbInstance = null;
+var SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS memories (
+  id TEXT PRIMARY KEY,
+  repo TEXT NOT NULL,
+  type TEXT NOT NULL CHECK (type IN ('convention', 'bug_fix', 'reviewer_pattern', 'decision', 'issue', 'general')),
+  note TEXT NOT NULL,
+  tags TEXT NOT NULL DEFAULT '[]',
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_memories_repo ON memories (repo);
+CREATE INDEX IF NOT EXISTS idx_memories_created_at ON memories (created_at DESC);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+  repo,
+  note,
+  content = 'memories',
+  content_rowid = 'rowid'
+);
+
+CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+  INSERT INTO memories_fts(rowid, repo, note) VALUES (new.rowid, new.repo, new.note);
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, repo, note) VALUES ('delete', old.rowid, old.repo, old.note);
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, repo, note) VALUES ('delete', old.rowid, old.repo, old.note);
+  INSERT INTO memories_fts(rowid, repo, note) VALUES (new.rowid, new.repo, new.note);
+END;
+`;
+function initDb(dbPath) {
+  if (dbInstance) {
+    return dbInstance;
+  }
+  mkdirSync(dirname(dbPath), { recursive: true });
+  const db = new Database(dbPath);
+  db.pragma("journal_mode = WAL");
+  db.pragma("foreign_keys = ON");
+  db.exec(SCHEMA_SQL);
+  dbInstance = db;
+  return db;
+}
+function getDb() {
+  if (!dbInstance) {
+    throw new Error("Database has not been initialized. Call initDb() first.");
+  }
+  return dbInstance;
+}
+
+// src/tools/delete.ts
+import { z } from "zod";
+var deleteMemoryInputSchema = {
+  id: z.string().trim().min(1, "id is required")
+};
+function registerDeleteMemoryTool(server) {
+  server.registerTool(
+    "delete_memory",
+    {
+      description: "Delete a memory from storage by id.",
+      inputSchema: deleteMemoryInputSchema
+    },
+    async ({ id }) => {
+      try {
+        const db = getDb();
+        const row = db.prepare("SELECT id FROM memories WHERE id = ?").get(id);
+        if (!row) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: `Memory ${id} not found.`
+              }
+            ]
+          };
+        }
+        const deleteTx = db.transaction((memoryId) => {
+          db.prepare("DELETE FROM memories WHERE id = ?").run(memoryId);
+        });
+        deleteTx(id);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Deleted memory ${id}.`
+            }
+          ]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error while deleting memory.";
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to delete memory: ${message}`
+            }
+          ]
+        };
+      }
+    }
+  );
+}
+
+// src/tools/get-repo.ts
+import { z as z2 } from "zod";
+var getRepoContextInputSchema = {
+  repo: z2.string().trim().min(1, "repo is required"),
+  limit: z2.number().int().positive().max(100).default(10)
+};
+function parseTags(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((value) => typeof value === "string") : [];
+  } catch {
+    return [];
+  }
+}
+function formatTypeHeading(type) {
+  return type.split("_").map((part) => part[0]?.toUpperCase() + part.slice(1)).join(" ");
+}
+function registerGetRepoContextTool(server) {
+  server.registerTool(
+    "get_repo_context",
+    {
+      description: "Get recent memories for a repository grouped by memory type.",
+      inputSchema: getRepoContextInputSchema
+    },
+    async ({ repo, limit }) => {
+      try {
+        const db = getDb();
+        const rows = db.prepare(
+          `
+              SELECT id, repo, type, note, tags, created_at, updated_at
+              FROM memories
+              WHERE repo = ?
+              ORDER BY updated_at DESC
+              LIMIT ?
+            `
+        ).all(repo, limit);
+        if (rows.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No memories found for ${repo}.`
+              }
+            ]
+          };
+        }
+        const grouped = /* @__PURE__ */ new Map();
+        for (const memory of rows) {
+          const tags = parseTags(memory.tags);
+          const tagSuffix = tags.length > 0 ? ` [tags: ${tags.join(", ")}]` : "";
+          const item = `- (${memory.id}) ${memory.note}${tagSuffix}`;
+          const existing = grouped.get(memory.type) ?? [];
+          existing.push(item);
+          grouped.set(memory.type, existing);
+        }
+        const sections = [];
+        for (const type of MEMORY_TYPES) {
+          const entries = grouped.get(type);
+          if (!entries || entries.length === 0) {
+            continue;
+          }
+          sections.push(`${formatTypeHeading(type)}
+${entries.join("\n")}`);
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Repository context for ${repo}
+Total memories: ${rows.length}
+
+${sections.join("\n\n")}`
+            }
+          ]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error while retrieving repository context.";
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to fetch repository context: ${message}`
+            }
+          ]
+        };
+      }
+    }
+  );
+}
+
+// src/tools/search.ts
+import { z as z3 } from "zod";
+var searchMemoryInputSchema = {
+  query: z3.string().trim().min(1, "query is required"),
+  repo: z3.string().trim().min(1).optional(),
+  limit: z3.number().int().positive().max(50).default(5)
+};
+function normalizeFtsQuery(query) {
+  const terms = query.trim().split(/\s+/).map((term) => term.replaceAll('"', '""')).filter(Boolean);
+  if (terms.length === 0) {
+    throw new Error("query must contain searchable text");
+  }
+  return terms.map((term) => `"${term}"`).join(" AND ");
+}
+function parseTags2(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((value) => typeof value === "string") : [];
+  } catch {
+    return [];
+  }
+}
+function registerSearchMemoryTool(server) {
+  server.registerTool(
+    "search_memory",
+    {
+      description: "Search memories using full-text search with optional repository filtering.",
+      inputSchema: searchMemoryInputSchema
+    },
+    async ({ query, repo, limit }) => {
+      try {
+        const db = getDb();
+        const ftsQuery = normalizeFtsQuery(query);
+        const rows = repo ? db.prepare(
+          `
+                  SELECT m.id, m.repo, m.type, m.note, m.tags, m.created_at, m.updated_at, bm25(memories_fts) AS rank
+                  FROM memories_fts
+                  JOIN memories AS m ON m.rowid = memories_fts.rowid
+                  WHERE memories_fts MATCH ? AND m.repo = ?
+                  ORDER BY rank
+                  LIMIT ?
+                `
+        ).all(ftsQuery, repo, limit) : db.prepare(
+          `
+                  SELECT m.id, m.repo, m.type, m.note, m.tags, m.created_at, m.updated_at, bm25(memories_fts) AS rank
+                  FROM memories_fts
+                  JOIN memories AS m ON m.rowid = memories_fts.rowid
+                  WHERE memories_fts MATCH ?
+                  ORDER BY rank
+                  LIMIT ?
+                `
+        ).all(ftsQuery, limit);
+        if (rows.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: repo ? `No memories matched "${query}" in ${repo}.` : `No memories matched "${query}".`
+              }
+            ]
+          };
+        }
+        const formatted = rows.map((row, index) => {
+          const tags = parseTags2(row.tags);
+          const tagsText = tags.length > 0 ? ` | tags: ${tags.join(", ")}` : "";
+          return `${index + 1}. [${row.repo}] ${row.type} (${row.id})
+${row.note}${tagsText}`;
+        }).join("\n\n");
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Search results for "${query}"${repo ? ` in ${repo}` : ""}:
+
+${formatted}`
+            }
+          ]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error while searching memory.";
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to search memories: ${message}`
+            }
+          ]
+        };
+      }
+    }
+  );
+}
+
+// src/tools/store.ts
+import { nanoid } from "nanoid";
+import { z as z4 } from "zod";
+var storeContextInputSchema = {
+  repo: z4.string().trim().min(1, "repo is required"),
+  type: z4.enum(MEMORY_TYPES),
+  note: z4.string().trim().min(1, "note is required"),
+  tags: z4.array(z4.string().trim().min(1)).optional()
+};
+function registerStoreContextTool(server) {
+  server.registerTool(
+    "store_context",
+    {
+      description: "Store repository-specific contributor context such as bug fixes, conventions, and decisions.",
+      inputSchema: storeContextInputSchema
+    },
+    async ({ repo, type, note, tags }) => {
+      try {
+        const db = getDb();
+        const now = Math.floor(Date.now() / 1e3);
+        const id = nanoid();
+        const normalizedTags = Array.from(
+          new Set((tags ?? []).map((tag) => tag.trim()).filter(Boolean))
+        );
+        db.prepare(
+          `
+            INSERT INTO memories (id, repo, type, note, tags, created_at, updated_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+          `
+        ).run(id, repo, type, note, JSON.stringify(normalizedTags), now, now);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Stored memory ${id} for ${repo} (${type}).`
+            }
+          ]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error while storing memory.";
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to store memory: ${message}`
+            }
+          ]
+        };
+      }
+    }
+  );
+}
+
+// src/index.ts
+async function main() {
+  const dbPath = process.env.FOSSYL_DB_PATH?.trim() || join(homedir(), ".fossyl", "memory.db");
+  initDb(dbPath);
+  const server = new McpServer({
+    name: "fossel",
+    version: "1.0.0"
+  });
+  registerStoreContextTool(server);
+  registerGetRepoContextTool(server);
+  registerSearchMemoryTool(server);
+  registerDeleteMemoryTool(server);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`Fossyl server failed to start: ${message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "fossel",
+  "version": "1.0.0",
+  "description": "Local MCP memory server for open-source contributors",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "fossel": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "smoke": "tsx scripts/smoke.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "latest",
+    "better-sqlite3": "latest",
+    "nanoid": "latest",
+    "zod": "latest"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "latest",
+    "@types/node": "latest",
+    "tsup": "latest",
+    "tsx": "latest",
+    "typescript": "latest"
+  }
+}