Publishing a site to GH Pages

.github/workflows/pages.yml

@@ -0,0 +1,59 @@
+# Build and publish the VecFS site (Hugo) to GitHub Pages.
+# Ensure GitHub Pages is set to "GitHub Actions" in repo Settings > Pages.
+#
+# Validation: the workflow runs on pull requests to main. The build job runs
+# (checkout, Hugo build); deploy is skipped. Use a PR to validate the site
+# builds before merging.
+
+name: Publish VecFS site to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v2
+        with:
+          hugo-version: "0.128.2"
+          extended: true
+
+      - name: Build
+        run: hugo --minify
+        working-directory: pages
+
+      - name: Upload Pages artifact
+        if: github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: pages/public
+
+  deploy:
+    if: github.event_name == 'push'
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,3 +1,10 @@
+.vscode/
+
+pages/public/
+**/*.log
+resources/
+.hugo_build.lock
+
 node_modules/
 dist/
 .venv/

pages/README.md

@@ -0,0 +1,52 @@
+# VecFS GitHub Pages (Hugo)
+
+This directory contains the [Hugo](https://gohugo.io/) source for the VecFS project site, built for GitHub Pages. The site uses the [Beautiful Hugo](https://github.com/halogenica/beautifulhugo) theme (Hugo module).
+
+## Prerequisites
+
+- [Hugo](https://gohugo.io/installation/) (v0.110+). If installed via Go, it may be at `~/go/bin/hugo`; ensure `~/go/bin` is on your PATH.
+
+## Build
+
+From this directory (`pages/`):
+
+```bash
+hugo --minify
+```
+
+The site uses Beautiful Hugo as a Hugo module; the first build will download the theme.
+
+Output is written to `public/`. To preview locally:
+
+```bash
+hugo server
+```
+
+Then open the URL shown (e.g. http://localhost:1313/). For GitHub Pages with project site base URL, use:
+
+```bash
+hugo server --baseURL http://localhost:1313/vecfs/
+```
+
+## Deploy to GitHub Pages
+
+A GitHub Actions workflow (`.github/workflows/pages.yml`) builds and publishes this site on every push to `main`:
+
+1. Checkout repo and run `hugo --minify` in `pages/`.
+2. Upload `pages/public/` as the Pages artifact and deploy.
+
+**One-time setup:** In the repository go to **Settings → Pages → Build and deployment**: set **Source** to **GitHub Actions**. After that, each successful run of the workflow will update the live site.
+
+**Validating the workflow:** The workflow also runs on pull requests targeting `main`. On a PR, only the build job runs; deploy is skipped. Open a PR that touches `pages/` or the workflow file to confirm the site builds in CI before merging.
+
+## Assets
+
+- **Logo** — `static/logo.svg` is a copy of `vecfs-plugin/assets/logo.svg`, used in the header and as favicon. Update the copy here if the plugin logo changes.
+
+## Content
+
+- **Home** — `content/_index.md` (from README.md)
+- **Requirements** — `content/docs/requirements/_index.md` (from docs/requirements.md)
+- **Releases** — `content/docs/releases/_index.md` plus one page per release note; links to `docs/release-notes/` in the repo are listed for reference.
+
+To add a new release note to the site: add a new file under `content/docs/releases/` (e.g. `0.1.2-Release-2026-03-01.md`) with Hugo front matter and the note body, and add a row to the table in `content/docs/releases/_index.md`.

pages/content/_index.md

@@ -0,0 +1,78 @@
+---
+title: "VecFS"
+description: "Lightweight, local-first vector storage for AI agent long-term memory"
+---
+
+**VecFS** (Vector File System) is a lightweight, local-first vector storage specification and implementation designed for AI agent long-term memory.
+
+(c) Copyright 2026 Warwick Molloy. Contribution to this project is supported and contributors will be recognised.
+
+## Overview
+
+VecFS gives AI agents a simple, efficient way to store and retrieve context locally. Through the Model Context Protocol (MCP), agents can learn from their interactions and recall relevant information in future sessions without the complexity of a full-scale vector database.
+
+## Key Features
+
+- **Sparse vector storage** — Follows the principle of "not storing zeros" for natural data compression and minimal disk footprint.
+- **Local-first** — Designed to run on a laptop (WSL2, Linux, macOS) with simple file-based storage.
+- **MCP integration** — Acts as an MCP server, providing tools for agents to `search`, `memorize`, `feedback`, and `delete` context.
+- **Agent skill** — Ships with a portable Agent Skill definition that teaches agents how to use long-term memory effectively.
+- **Embedding script** — Includes a model-agnostic Python tool for converting text to sparse vectors.
+
+## Quick Start
+
+### Install from GitHub (no npm or pip)
+
+Clone the repo and run the installer. You only need Node.js and Python runtimes.
+
+```bash
+git clone https://github.com/WazzaMo/vecfs.git
+cd vecfs
+./install-from-github.sh
+```
+
+This installs into `~/.local` by default. Add `~/.local/bin` to your PATH if needed.
+
+### Install the MCP server (npm)
+
+```bash
+npm install -g vecfs
+```
+
+Or run directly without installing:
+
+```bash
+npx vecfs
+```
+
+### Agent configuration
+
+Add VecFS to your agent's MCP configuration (Claude Desktop, Cursor, etc.):
+
+```json
+{
+  "mcpServers": {
+    "vecfs": {
+      "command": "npx",
+      "args": ["-y", "vecfs"],
+      "env": {
+        "VECFS_FILE": "/path/to/memory.jsonl"
+      }
+    }
+  }
+}
+```
+
+## Transport modes
+
+- **Stdio (default)** — `vecfs` — Used with CLI-based agents. Simple, secure, no network ports.
+- **HTTP / SSE** — `vecfs --http` or `PORT=8080 vecfs --http` — For remote agents or debugging.
+
+## Documentation
+
+- [Requirements](/vecfs/docs/requirements/) — Technical requirements for the MCP server and storage layer.
+- [Releases](/vecfs/docs/releases/) — Release notes and version history.
+
+## License
+
+This project is licensed under the Apache License, Version 2.0.

pages/content/docs/_index.md

@@ -0,0 +1,8 @@
+---
+title: "Documentation"
+description: "VecFS documentation"
+weight: 10
+bookFlatSection: true
+---
+
+Documentation for VecFS: requirements, release notes, and more.

pages/content/docs/releases/0.1.1-Release-2026-02-21.md

@@ -0,0 +1,61 @@
+---
+title: "Release 0.1.1 (2026-02-21)"
+description: "Decision-aware memory, doc guide, MCP and plugin improvements"
+date: 2026-02-21
+weight: 1
+---
+
+# Summary
+
+This release adds decision-aware memory behaviour to the vecfs-memory skill, clarifies documentation layout in the doc guide, and includes MCP server and plugin improvements.
+
+## Skills
+
+### vecfs-memory: decisions in memory and context sweep
+
+The vecfs-memory skill (plugin and standalone) now treats project decisions as first-class memory.
+
+#### When to activate
+
+The skill activates when the conversation or a markdown file indicates that a decision has been made.
+
+#### Storing decisions
+
+Decisions detected in user-agent conversation or in markdown (e.g. "we decided to use X", "Decision: ...") are summarised and stored via the `memorize` tool with metadata such as `{"type": "decision"}`.
+
+#### Context sweep
+
+Stored decisions are discovered like other memories during a context sweep; agents incorporate recalled decisions into reasoning and mention them when they affect the current task.
+
+Both `vecfs-plugin/skills/vecfs-memory/SKILL.md` and `vecfs-memory/SKILL.md` are aligned on this behaviour.
+
+## MCP server
+
+#### Vector input
+
+The server now accepts vectors as either JSON objects or JSON strings, improving compatibility with callers that serialise parameters differently.
+
+#### Feedback
+
+Support for score adjustments (rankings) on feedback is included in this version.
+
+## Plugin and installation
+
+- Cursor plugin layout and marketplace metadata are in place under `vecfs-plugin/`, with the vecfs-memory skill bundled.
+- Installation from GitHub is documented and supported via `install-from-github.sh`.
+
+## Documentation
+
+### Doc guide: purposeful markdown
+
+The doc guide (`docs/doc-guide.md`) now defines where and how to use certain markdown artefacts:
+
+#### Notes
+
+Live in `docs/notes/`, prefixed with the date (YYYY-MM-DD) and a short topic name.
+
+#### Release notes
+
+Live in `docs/release-notes/`, with the naming convention `{semver}-Release-{date}.md`. They summarise significant changes in vecfs_embed, the MCP server, and skills for each release.
+
+This release note follows that convention.

pages/content/docs/releases/_index.md

@@ -0,0 +1,23 @@
+---
+title: "Releases"
+description: "Release notes and version history for VecFS"
+weight: 30
+---
+
+# Releases
+
+Release notes for VecFS are listed below. Each note summarises significant changes in the embedding script (vecfs_embed), the MCP server, and skills for that release.
+
+## Release notes (this site)
+
+| Release | Date | Notes |
+|---------|------|--------|
+| [0.1.1](/vecfs/docs/releases/0.1.1-Release-2026-02-21/) | 2026-02-21 | Decision-aware memory, doc guide, MCP and plugin improvements |
+
+## Release notes (repository)
+
+The canonical release note files live in the repository under `docs/release-notes/` with the naming convention `{semver}-Release-{date}.md`:
+
+- [0.1.1-Release-2026-02-21.md](https://github.com/WazzaMo/vecfs/blob/main/docs/release-notes/0.1.1-Release-2026-02-21.md) — 0.1.1 (2026-02-21)
+
+Future releases will be added here and linked to their `docs/release-notes/` counterparts.