Skillget

vellis

mcp
Security Audit
Warn
Health Warn
  • License — License: Apache-2.0
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 6 GitHub stars
Code Pass
  • Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

Vellis — open-source context graph engine for AI agents: typed, local-first memory with explicit schema, validated change, deterministic query, migration, snapshots, replay, and audit. MCP-native. Apache-2.0.

README.md

Vellis

Vellis is an open-source context graph engine for AI agents — a typed, local-first
knowledge system your agents connect to over MCP (Model Context Protocol) and use as durable,
shared memory. Where most agent-memory layers extract-and-embed, Vellis stores meaning
explicitly: a schema you can read, validation on every change, deterministic query, migration,
audit, snapshots, and replay. Your graph lives on your machine, in your repo, under Apache-2.0
— it is yours to keep, move, or rebuild.

Use it as a personal context graph (one memory across Claude, Codex, and other MCP-capable
tools), as a team knowledge substrate, or as the storage layer for agents working on their own.

Technically, Vellis is an RTG (Reified Typed Graph) knowledge system. This repository contains
two deliberately separate products while early adopters benefit from a single clone:

  • Bibliotek is the reusable AI-native software component library.
  • Vellis is the first application composed from Bibliotek: the RTG knowledge system
    described above.

The repository is clone-and-run for beta and open-source evaluation. It gives first-time users
two entry points:

  • Use Vellis: run the RTG Knowledge Graph application through MCP (Model Context Protocol)
    as a full-service knowledge substrate with schema, data CRUD (Create, Read, Update, Delete),
    query, validation, migration, audit, snapshots, restore, adjust, replay, plus agent-facing state
    summaries and usage guides.
  • Build with the components: use the storage, RTG graph, schema, migration, validation, query,
    and controller components as reusable building blocks for follow-on applications.

The library and application are independently modeled and packageable even though their Python
sources currently share this repository. Bibliotek never depends on Vellis. In a future repository
layout, each can move to its own repo without changing the component contracts.

Start Here: Use Vellis With An AI Agent

Install Git and uv, clone the repo, and enter the checkout. You do not need to install Python or
just: uv provisions the required Python and locked runtime dependencies automatically.

# macOS (Homebrew)
brew install git uv

# macOS/Linux (standalone uv installer)
curl -LsSf https://astral.sh/uv/install.sh | sh

git clone https://github.com/volantlabs/vellis.git
cd vellis

On native Windows, use PowerShell:

winget install --id Git.Git -e
winget install --id astral-sh.uv -e
# Open a new PowerShell window after installation.
git clone https://github.com/volantlabs/vellis.git
cd vellis

Run setup. The first uv run may download Python and dependencies; later runs reuse them.

uv run vellis setup

Setup detects Codex, Claude Code, or Claude Desktop, shows its intended user-wide MCP change, asks
once, recovers any existing durable graph, and installs the modeled Everyday Life schema only when
the graph is genuinely empty. It never invents people, tasks, or other facts. Restart or reload the
selected client, then say:

Help me start using Vellis to remember and organize things across my personal life, household or
family responsibilities, and work. Use the schema already installed. Ask before assuming missing
details and show me what you propose before making a large initial write.

That is the complete ordinary setup path—no MCP JSON editing, raw tool calls, schema construction,
or snapshots are required. State is stored unencrypted under .data/rtg_knowledge_graph/, ignored
by Git, and recovered automatically across MCP process restarts. See the
plain-language getting-started guide for backups, reset,
troubleshooting with uv run vellis doctor, shared-family use, and advanced local HTTP mode.

For scripts and agents, setup --json and doctor --json print exactly one JSON document and never
prompt. Supply the choices explicitly, for example
uv run vellis setup --json --client codex --yes or
uv run vellis doctor --json --client codex.

Design Values

Vellis favors modular, reusable components with narrow scope and explicit invariant ownership.

Good components are:

  • focused on one coherent responsibility
  • reusable outside a single application, transport, runtime, or storage choice
  • clear about owned state, public contracts, dependencies, and non-responsibilities
  • low-coupling, using public contracts instead of private internals
  • simple and elegant, with one clear representation per operation
  • verifiable at the boundary with contract, side-effect, and dependency checks

These values keep systems easier to understand, maintain, test, and extend as the component library grows.

The model-based engineering vision explains how
humans can focus on intent and architectural judgment while agents help maintain the model,
realizations, projections, and verification evidence.

Current Focus

Vellis evolves in this order:

  1. Build a coherent component library.
  2. Ship Vellis as the first turnkey application assembled from those components.
  3. Add tooling and SDK surfaces for building software from component models.
  4. Add runtime support, including distributed-runtime patterns, when component contracts justify it.

Current generated component views include:

Current Python implementations include:

The first application is:

  • apps/rtg_knowledge_graph: the Vellis RTG Knowledge Graph app. It
    wires JSON File Storage, SQL Storage, and the in-process RTG controller, then exposes the modeled
    Vellis façade through local MCP transports for human/agent knowledge-system workflows.
  • Vellis application model reference: composition, actor-visible
    use cases, façade requirements, verification, and MCP realization mappings.

The RTG Knowledge Graph MCP server uses standalone FastMCP v3 from the fastmcp package.

Manual evaluation prompts include:

Component Models

Textual SysML v2 under model/ is the normative black-box design for Bibliotek and
Vellis. It captures typed public actions and values, abstract owned state, action effects,
principal failures, collaborator roles, invariants, application composition, use cases, and
realizations. Human-readable pages under generated/reference/ are
generated projections and must not be edited as alternate specifications.

Textual SysML is the normative design authority. The pinned official Java validator enforces SysML
syntax, linking, and semantic validation. Reviewed implementation disagreements have been resolved
in the model and Python realization; future disagreements must return through model review instead
of silently changing either side. See the non-normative
open model-design questions for possible future evolution and
docs/engineering/sysml-modeling.md for the modeling profile.

A component model defines:

  • purpose
  • public values/items and provided/required actions
  • abstract owned state and action read/write effects
  • principal failures and no-effect guarantees
  • invariants and contract-significant behavior
  • verification objectives

Models use lifecycle statuses:

  • draft: proposed boundary for discussion or early implementation
  • accepted: human-approved and normative for implementation
  • deprecated: valid for existing consumers, but closed to new consumers
  • retired: historical only

Only a human owner may move a component to accepted, deprecated, or retired.

Python Components

Component models are language-neutral contracts; Python is the first implementation target, not the only possible one. Other language implementations may be produced from the same model without changing its meaning.

Each component should have its own directory. By default, map component IDs to implementation directories by removing the component. prefix and replacing dots with path separators:

component.<domain>.<name> -> components/<domain>/<name>/

The default shape is:

components/<domain>/<name>/
  __init__.py
  protocol.py
  implementation.py
  reference.py
  tests/
    test_<domain>_<name>_contract.py

Use protocol.py for the public Python boundary, implementation.py for the concrete class that owns state and invariants, reference.py for a runnable reference composition, and tests/ for boundary-focused verification.

Development Setup

Vellis is consumed clone-and-run for beta testing: clone the repository and run components, apps, and tools in place. Package metadata is buildable for release validation, but no distribution is currently published.

The repo uses uv for Python environment and dependency management, and just as the task runner. Python 3.14 is required, but uv provisions it automatically — no manual Python install needed.

Install the prerequisites and clone the repo:

# macOS
brew install uv just

# or without Homebrew
curl -LsSf https://astral.sh/uv/install.sh | sh
# just install options: https://just.systems/man/en/packages.html

git clone https://github.com/volantlabs/vellis.git
cd vellis

Set up the local development environment:

just setup
just model-setup

just model-setup downloads and checksum-verifies the pinned model references and validator assets
required by the model checks. Run it once after cloning and again when the model lock files change.

Then run checks:

just check

Useful recipes:

  • just setup: create or update the uv-managed .venv
  • just test: run tests when tests exist
  • just lint: run Ruff checks
  • just typecheck: run BasedPyright checks
  • just format: format Python code with Ruff
  • just build: build source and wheel distributions for release validation
  • just model-setup: fetch and verify the official Java validator, formal libraries, and Java runtime
  • just model-reference-render: regenerate searchable SysML/KerML pages from pinned official PDFs
  • just model-reference-check: verify the committed specification corpus against those PDFs
  • just model-reference-find "<question>": find ranked SysML/KerML sections and source pages
  • just model-check: validate packaged model products plus architecture, realization, and generated files
  • just model-check-formal: run the pinned official SysML validator directly
  • just model-render: regenerate the parser inventory, conformance objectives, views, and manifest
  • just model-package: build independently packageable KPAR products
  • just model-diff: review authored model, generated projection, and runtime-manifest changes
  • just model-handoff TARGET=<stable-id>: inspect a model slice for an implementation handoff
  • just model-audit [stable-id]: collect an advisory model/implementation drift evidence bundle
  • just skills-check: validate repo-local skill metadata
  • just skills-sync: expose source-of-truth repo skills in Claude Code's project-skill layout
  • just rtg: launch the RTG Knowledge Graph app with default local .data/ storage
  • uv run vellis setup: install/recover the starter schema and configure a local MCP client
  • uv run vellis doctor: non-destructively inspect local state and client registration
  • just rtg-mcp-config: print only copy-pastable stdio MCP client configuration
  • just rtg-mcp-info: print default stdio MCP client config, prompt paths, and first-call smoke check
  • just rtg-mcp: launch the default RTG Knowledge Graph stdio MCP server
  • just rtg-mcp-http-info: print localhost HTTP MCP URL config for another local agent
  • just rtg-mcp-http: launch the unauthenticated localhost HTTP MCP server
  • just rtg-eval-info: print detailed beta eval MCP metadata with .data/vellis-beta-001 storage
  • just run-rtg-knowledge-graph: launch the RTG Knowledge Graph app
  • just run-rtg-knowledge-graph-mcp: launch the RTG Knowledge Graph MCP server
  • just run-rtg-knowledge-graph-mcp-info: print RTG MCP dry-run metadata and client config
  • vellis: short console script for setup, doctor, and the RTG Knowledge Graph app
  • vellis-rtg-knowledge-graph: preserved compatibility console script
  • just check: run lint, type checking, skill validation, model checks, and tests

Launch the first application with the default local .data/ storage:

just rtg

When the project is installed in the uv environment, the same app is available as:

uv run vellis-rtg-knowledge-graph --json

For protocol debugging only, print MCP client configuration for the default local app:

just rtg-mcp-config

The output is the complete mcpServers JSON block. It uses absolute executable, repository,
storage, and SQLite paths so GUI clients do not need to inherit your shell's working directory or
PATH. The MCP client starts the configured stdio server; do not also run just rtg or
just rtg-mcp. An ordinary app recovers durable state and reports the installed starter schema.
Use just rtg-mcp-info only when you need the larger diagnostic payload containing prompt
paths, transports, tool metadata, and the smoke-check expectation.

For modular same-machine use, run the localhost HTTP server:

just rtg-mcp-http .data/vellis-beta-001 127.0.0.1 8765 /mcp

The URL client config is in mcp.transports.localhost_http.client_config; the endpoint is
http://127.0.0.1:8765/mcp.

For a developer beta eval with explicit blank/manual-recovery state:

just rtg-eval-info .data/vellis-beta-001

Run ad hoc Python commands through uv run:

uv run python --version

Repository Guidance

Agent and contributor operating rules live in AGENTS.md. In short:

  • preserve component boundaries
  • update the normative SysML model when public behavior changes
  • prefer focused, reusable components over one-off application code
  • use uv and just for Python work
  • verify changes at the component boundary

Repo-local agent skills live in .agents/skills/. This is the source of truth for Vellis skills, including the RTG MCP usage skill. Claude Code project-skill exposure lives under .claude/skills/ as symlinks back to .agents/skills; run just skills-sync to recreate those links and just skills-check to validate them.

Community And Release

Status

This repository is beta-stage. The SysML component-model system, Python project infrastructure, initial component implementations, and local RTG Knowledge Graph eval path are in place.

Reviews (0)

No results found