diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..58ab1a4 --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore index fabe406..8530f79 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,10 @@ +.vscode/ + +pages/public/ +**/*.log +resources/ +.hugo_build.lock + node_modules/ dist/ .venv/ diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..e69de29 diff --git a/pages/.nojekyll b/pages/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/pages/README.md b/pages/README.md new file mode 100644 index 0000000..7a11554 --- /dev/null +++ b/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`. diff --git a/pages/content/_index.md b/pages/content/_index.md new file mode 100644 index 0000000..2e7e985 --- /dev/null +++ b/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. diff --git a/pages/content/docs/_index.md b/pages/content/docs/_index.md new file mode 100644 index 0000000..895c5b6 --- /dev/null +++ b/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. diff --git a/pages/content/docs/releases/0.1.1-Release-2026-02-21.md b/pages/content/docs/releases/0.1.1-Release-2026-02-21.md new file mode 100644 index 0000000..d8564b8 --- /dev/null +++ b/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. diff --git a/pages/content/docs/releases/_index.md b/pages/content/docs/releases/_index.md new file mode 100644 index 0000000..de8184b --- /dev/null +++ b/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. diff --git a/pages/content/docs/requirements/_index.md b/pages/content/docs/requirements/_index.md new file mode 100644 index 0000000..29418ae --- /dev/null +++ b/pages/content/docs/requirements/_index.md @@ -0,0 +1,144 @@ +--- +title: "Requirements" +description: "Technical requirements for the VecFS MCP server and storage layer" +weight: 20 +--- + +# Requirements for VecFS MCP Server + +VecFS provides a lightweight, local vector storage mechanism designed for AI agent memory. The MCP (Model Context Protocol) server acts as the interface between the agent and the VecFS storage layer. + +## Functional Requirements + +The MCP server must implement the following core functionalities to enable a seamless context loop for agents. + +### Providing Context to an Agent + +The MCP server should expose VecFS data as resources or via tools that the agent can query. + +#### Search Tool + +The server shall provide a `search` tool that allows an agent to query the vector space using natural language or existing vector embeddings. + +#### Context Injection + +The server shall support "context injection" where relevant snippets from the vector store are automatically suggested or provided based on the current task. + +#### URI Addressing + +Resources should be addressable via URIs that the agent can reference to retrieve specific learned items. + +### Storing and Contributing Context + +To allow an agent to "learn," it must be able to write back information to VecFS. + +#### Storage Tool + +The server shall provide a `memorize` or `store` tool that accepts text content, generates an embedding (or accepts one), and stores it in the VecFS format. + +#### Sparse Storage + +The storage process must adhere to the VecFS principle of "not storing zeros," ensuring that the local file remains compact. + +#### Memory Updates + +The server shall allow updating existing memory entries if the agent learns new information that expands upon previous entries. + +### Reinforcement and Feedback + +Recording feedback allows the agent to improve its recall quality over time based on user or system validation. + +#### Feedback Tool + +The server shall provide a `feedback` tool to record positive or negative reinforcement (e.g., a score or sentiment) for specific context or actions. + +#### Weighting + +Feedback scores shall be used to influence the ranking of results in future searches, prioritizing positively reinforced context. + +#### Persistence + +Reinforcement data must be stored alongside or associated with the relevant vector entries in the VecFS file. + +### Search and Retrieval Mechanism + +#### Vector Transformation + +The server must handle the transformation of agent queries into the vector space. + +#### Local Performance + +Retrieval must be performant enough for real-time interaction on a local machine (e.g., WSL2/Linux/Mac). + +#### Metadata Filtering + +The server should support filtering based on metadata (e.g., tags, timestamps, or project context). + +## Integration Requirements + +### Agent Interaction Flow + +The success of the system depends on how the agent uses the MCP server. + +```mermaid +sequenceDiagram + participant Agent + participant MCP as MCP Server + participant VecFS as VecFS File + + Agent->>MCP: 1. Search Request + MCP->>VecFS: 2. Query Vector Space + VecFS->>MCP: 3. Results + MCP->>Agent: 4. Context + Agent->>MCP: 5. Learn/Update + Agent->>MCP: 6. Provide Feedback + MCP->>VecFS: 7. Store Sparse Vector / Score +``` + +### Interaction Steps + +#### Context Acquisition + +When starting a task, the agent proactively searches the MCP server for relevant historical context. + +#### Context Contribution + +After completing a task or learning a new fact, the agent uses the `store` tool to commit this knowledge to long-term memory. + +#### Feedback Loop + +The agent or user provides reinforcement signals to the MCP server to refine future context retrieval. + +## System Requirements + +To be successful, the VecFS MCP implementation must meet these criteria: + +### Local First + +No dependency on external vector databases; all storage must be in local VecFS files. + +### Efficiency + +The system must implement the sparse vector storage model described in the goals, minimizing disk I/O and memory usage. + +### Simplicity + +The server should be easy to install and configure as a standard MCP server (e.g., via `npx` or `pip`). + +### Reliability + +Data must be stored in a way that is robust against corruption and easy to back up (simple file copy). + +## Success Criteria + +### Recall Accuracy + +The agent can successfully retrieve relevant information from past sessions with high precision, improved by reinforcement. + +### Storage Footprint + +The VecFS file size should be significantly smaller than a dense vector representation of the same data. + +### Low Latency + +Context retrieval should add negligible overhead to the agent's response time. diff --git a/pages/go.mod b/pages/go.mod new file mode 100644 index 0000000..8f8cc0f --- /dev/null +++ b/pages/go.mod @@ -0,0 +1,7 @@ +module github.com/WazzaMo/vecfs/pages + +go 1.22.2 + +require ( + github.com/halogenica/beautifulhugo v0.0.0-20260205145405-beb9bfe3f6ba // indirect +) diff --git a/pages/go.sum b/pages/go.sum new file mode 100644 index 0000000..34ab2eb --- /dev/null +++ b/pages/go.sum @@ -0,0 +1,2 @@ +github.com/halogenica/beautifulhugo v0.0.0-20260205145405-beb9bfe3f6ba h1:EfDzKDJhUN0+PG3o5IdVGXD9y0ToJ5VDuwG0sEB4omg= +github.com/halogenica/beautifulhugo v0.0.0-20260205145405-beb9bfe3f6ba/go.mod h1:4dwHt6njigk+fr9W3Bg+OflL4LKzkjbXAULXvr3mYLs= diff --git a/pages/hugo.toml b/pages/hugo.toml new file mode 100644 index 0000000..f27f009 --- /dev/null +++ b/pages/hugo.toml @@ -0,0 +1,33 @@ +baseURL = "https://wazzamo.github.io/vecfs/" +languageCode = "en-us" +title = "VecFS" +theme = "github.com/halogenica/beautifulhugo" +publishDir = "public" + +[module] + [[module.imports]] + path = "github.com/halogenica/beautifulhugo" + disable = false + +[params] + showPageDates = false + [params.author] + name = "VecFS" + website = "https://github.com/WazzaMo/vecfs" + github = "WazzaMo/vecfs" + +[outputs] + home = ["HTML", "RSS"] + +[markup] + [markup.goldmark.renderer] + unsafe = true + [markup.highlight] + anchorLineNos = false + codeFences = true + guessSyntax = true + lineNoStart = 1 + lineNos = false + noClasses = false + style = "github" + tabWidth = 4 diff --git a/pages/static/logo.svg b/pages/static/logo.svg new file mode 100644 index 0000000..981a5da --- /dev/null +++ b/pages/static/logo.svg @@ -0,0 +1,20 @@ + + + + + + + + + + + + + + + + vecfs + longer memory + for AI Agents + + diff --git a/vecfs-plugin/assets/logo-org.svg b/vecfs-plugin/assets/logo-org.svg new file mode 100644 index 0000000..4383327 --- /dev/null +++ b/vecfs-plugin/assets/logo-org.svg @@ -0,0 +1,18 @@ + + + + + + + + + + + + + + + + vecfs + + diff --git a/vecfs-plugin/assets/logo.svg b/vecfs-plugin/assets/logo.svg index 4383327..981a5da 100644 --- a/vecfs-plugin/assets/logo.svg +++ b/vecfs-plugin/assets/logo.svg @@ -8,11 +8,13 @@ - + - + - vecfs + vecfs + longer memory + for AI Agents