vellum-ai/vellum-assistant

Overview

What it is — Vellum Assistant is a self-hosted, open-source personal AI assistant with persistent hybrid memory, configurable personality files, and proactive outreach across macOS, Telegram, and Slack.
Problem — AI tools are stateless and generic; this solves the lack of continuity, evolving context, and self-initiated action in everyday AI assistant use.
Who it's for — Technically capable individuals who want a persistent, private, extensible AI assistant they own and can shape rather than a managed SaaS product.
Notable — Ships with a fail-closed multi-actor trust engine, hybrid dense+sparse memory retrieval with per-type staleness windows, and a SOUL.md/NOW.md identity framework where the assistant writes its own personality — v0.8.5 released the day before this appraisal.

Verdict

	Rating	Summary
Quality	solid (19/24)	Actively maintained, well-documented TypeScript project with strong adoption growth — docked for missing dependency manifest, no visible test infrastructure, and no CI badge.
PAI Relevance	INTEGRATE (0.75)	Novel memory architecture, fail-closed trust engine, and NOW.md/SOUL.md identity patterns map directly to PAI gaps; TypeScript/Bun stack is a drop-in fit.

Quality Assessment

19/24 — actively-maintained / well-documented / solid

Health: 7/8 (actively-maintained)

Failed:

H8: FAIL — README badges are Docs, Discord, License, and Built by Vellum; no CI/build-status badge visible and no .github/workflows/ reference in the provided README content.

Passed:

H1: PASS — v0.8.5 released 2026-05-26T23:52:19Z.
H2: PASS — release is one day old at appraisal time.
H3: PASS — last commit 2026-05-27T18:36:55Z, well within 6 months.
H4: PASS — last commit is today (2026-05-27).
H5: PASS — archived: false.
H6: PASS — 18 open issues; above zero (triaged) and well below 100.
H7: PASS — MIT license declared.

Documentation: 7/8 (well-documented)

Failed:

D8: FAIL — no explicit Limitations, Caveats, Known Issues, or Trade-offs section heading found; inline note ("The CLI works but the desktop app is our primary focus") does not constitute a named section.

Passed:

D1: PASS — README is present and substantial.
D2: PASS — README is several KB with multiple tables, sections, and code blocks.
D3: PASS — "Get started" and CLI sections provide step-by-step install and setup instructions including bun install -g vellum and ./setup.sh.
D4: PASS — CLI section contains code blocks with concrete command examples under named headings.
D5: PASS — "Common commands" section enumerates CLI commands with descriptions.
D6: PASS — Purpose stated in the banner paragraph: "A personal AI assistant that evolves with you. It learns how you work, remembers what matters, and acts before you ask."
D7: PASS — Links to vellum.ai/docs and vellum.ai/community in both badge row and documentation table.

Engineering Signals: 5/8 (solid)

Failed:

E2: FAIL — dependency manifest not available in the provided repository data.
E3: FAIL — dependency count cannot be assessed without manifest.
E4: FAIL — no mention of test suite, test script, or CI test references in the README content provided.

Passed:

E1: PASS — primary language is TypeScript.
E5: PASS — 492 stars, well above the 50-star threshold.
E6: PASS — created 2026-02-07; ~3.7 months elapsed; ~133 stars/month, far exceeding the 2/month threshold.
E7: PASS — 75 forks, above the 5-fork threshold.
E8: PASS — description is meaningful, specific, and 87 characters.

PAI Relevance

Dimension	Score	Assessment
Harvest Value	2	SOUL.md self-authored personality evolution, NOW.md as ephemeral focus scratchpad, and hybrid dense+sparse retrieval with per-type staleness windows are novel patterns directly applicable to PAI's memory subsystem and the Algorithm's Observe phase; no equivalent exists in the current PAI manifest.
Integration Readiness	2	TypeScript codebase with explicit `bun install -g vellum` CLI install path; CLI-first command surface (`vellum wake`, `vellum client`, `vellum ps`); self-hosted option available; MIT license — drop-in fit with PAI's Bun/TypeScript/CLI-first stack.
Overlap Risk	1	Partial overlap: the Knowledge skill covers persistent knowledge graph storage, and the Loop/Algorithm execution cycle partially mirrors the hourly proactive self-check pattern; full personal-assistant scope is PAI's own domain. Trust engine (Silas/security) overlaps partially but is not equivalent to the fail-closed guardian/trusted/unknown resolution model here.
Gap Fill	1	Addresses two areas of limited PAI coverage: multi-channel coordination with shared memory across discrete surfaces (macOS/Telegram/Slack) and a structured multi-actor fail-closed trust resolution framework — Silas handles adversarial security review but there is no full actor-identity resolution layer in the current PAI manifest.

Composite: 0.75

What Next

Capture-to-Knowledge Pipeline (currently in design phase): Self-host vellum-assistant and configure its hybrid memory layer's per-type staleness windows to match the capture taxonomy — short window for ephemeral notes, medium for working ideas, long for durable references. Wire the pipeline's validated captures to vellum-assistant's memory ingestion endpoint rather than designing a bespoke retention system from scratch. — The pipeline gains a queryable, staleness-aware memory store with dense+sparse retrieval already implemented, collapsing one of the harder open design problems into a configuration exercise.
Petites Fugues advisory continuity: Deploy vellum-assistant with Telegram integration and author a NOW.md tracking active Petites Fugues threads — open inventory decisions, pricing reviews, upcoming seasonal buying windows. Set a proactive reach-out trigger for time-sensitive advisory items (e.g., a weekly prompt surfacing threads that have gone quiet). — Advisory context persists across weeks without manually reconstructing it from email at each engagement; the assistant surfaces relevant prior discussion before each check-in.
fab conversational front-end for V3: Author a SOUL.md encoding the fab V2.1 pattern library as domain expertise and configure vellum-assistant's Slack integration as a conversational interface for pattern recommendations. As patterns are invoked, have the assistant log usage observations into its identity files. — Pattern recommendations become session-aware and accumulate a per-content-type usage history, improving recommendation quality beyond what the stateless CLI currently delivers without requiring a rewrite of fab's core logic.

Landscape Position

Category: Personal AI & Knowledge

In this category: tinyhumansai--openhuman (excellent, 21/24, skip — Rust) is the direct prior entry; vellum-ai--vellum-assistant is the first TypeScript entry and the first with an explicit managed+local dual-mode deployment model.

Standing: Slightly lower quality score than openhuman (19 vs 21) but far stronger PAI fit (integrate vs skip) owing to TypeScript stack alignment and the novel NOW.md/trust-engine patterns that openhuman's Rust implementation cannot offer as a drop-in; the two repos address the same user problem from opposite ends of the build-vs-own spectrum.

Evidence Base

Density: 9/10 — Available: full description, topics, stars/forks/issues, license, creation date, last commit, latest release metadata, archived status, first 8KB of README. Missing: dependency manifest (explicitly noted as unavailable), full README beyond 8KB truncation, CI workflow files, source code structure.

Notes

The SOUL.md / NOW.md document pair is worth isolating as a study artifact independent of the full assistant: the pattern of separating durable identity (SOUL.md) from ephemeral focus state (NOW.md) maps directly onto PAI's ISA + Algorithm execution model and could inform how PAI's Observe phase captures working context across sessions. The proactive hourly self-check loop (re-reads notes, detects unfinished items, routes notifications to the right channel) is a concrete reference implementation of what PAI's Loop skill approximates — worth reading the implementation once available.