vellum

package module

v0.1.0 Latest Latest Go to latest Published: Jul 3, 2026 License: MIT Imports: 0 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/freema/vellum

Links

Open Source Insights

README ¶

vellum

A lightweight, self-hosted MCP server over a folder of markdown files. One static Go binary (with an embedded React SPA), one Docker image. docker compose up -d and you're done.

Status: work in progress — walking skeleton. Vault, MCP tools, OAuth and the web UI are being built milestone by milestone.

Principles

Your data is flat markdown. Portable, readable in any editor, git or Obsidian. No lock-in.
vellum never calls an LLM itself. Curation prepares context; the agent on the user's side decides.
The vault layer is dumb and deterministic. No database — config via env + vellum.yaml.
Structure is a feature. inbox/, projects/, archive/ — not a pile of files.

Quick start

docker compose up -d
curl http://localhost:8080/healthz

Development

Requires Go 1.23+ and Task.

task build        # build ./bin/vellum
task run          # run locally
task test         # go test ./...
task lint         # golangci-lint
task docker-build # build the Docker image
task docker-run   # docker compose up

Configuration

Variable	Default	Description
`PORT`	`8080`	HTTP listen port
`VELLUM_VAULT_PATH`	`./vault`	Path to the markdown vault directory

More configuration (auth, structure, curator) lands with upcoming milestones.

License

MIT

Documentation ¶

Overview ¶

Package vellum is the module root. Once the React SPA exists, this file will embed web/dist into the binary via //go:embed (PHY-116).

Source Files ¶

View all Source files

embed.go

Directories ¶

Path	Synopsis
cmd
vellum command Command vellum is a lightweight, self-hosted MCP server over a folder of markdown files.	Command vellum is a lightweight, self-hosted MCP server over a folder of markdown files.
internal
auth Package auth implements OAuth 2.1 issuer + resource server with a single pre-configured client secret, ported from openclaw-mcp (PHY-112).	Package auth implements OAuth 2.1 issuer + resource server with a single pre-configured client secret, ported from openclaw-mcp (PHY-112).
config Package config loads vellum configuration from environment variables.	Package config loads vellum configuration from environment variables.
httpapi Package httpapi provides the HTTP surface of vellum: health endpoint, the /mcp mount, and later the JSON REST API for the SPA (/api/*).	Package httpapi provides the HTTP surface of vellum: health endpoint, the /mcp mount, and later the JSON REST API for the SPA (/api/*).
mcpserver Package mcpserver exposes vault operations as MCP tools over the Streamable HTTP transport (PHY-111).	Package mcpserver exposes vault operations as MCP tools over the Streamable HTTP transport (PHY-111).
vault Package vault implements the dumb, deterministic file layer over the markdown vault: CRUD with path traversal protection and optimistic concurrency via content hashes (PHY-106).	Package vault implements the dumb, deterministic file layer over the markdown vault: CRUD with path traversal protection and optimistic concurrency via content hashes (PHY-106).

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL