# freelance

> Graph-based workflow enforcement and persistent memory for AI coding agents.  Define structured workflows in YAML. Enforce them at tool boundaries via MCP. Build a persistent knowledge graph that grow

- **URL**: https://www.freshcrate.ai/projects/freelance
- **Author**: duct-tape-and-markdown
- **Category**: MCP Servers
- **Latest version**: `v1.4.1` (2026-04-22)
- **License**: MIT
- **Source**: https://github.com/duct-tape-and-markdown/freelance
- **Language**: TypeScript
- **GitHub**: 7 stars, 4 forks
- **Registry**: github (`duct-tape-and-markdown/freelance`)
- **Tags**: `ai`, `cli`, `mcp`, `memory`, `typescript`, `workflow`

## Description

Graph-based workflow enforcement and persistent memory for AI coding agents.  Define structured workflows in YAML. Enforce them at tool boundaries via MCP. Build a persistent knowledge graph that grows with every query and knows when its sources have changed.

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `v1.4.1` | 2026-04-22 | High | ## Fixed  **Plugin SessionStart nudge detects CLI install state and recommends matching the plugin version.**  Post-1.4 the plugin no longer ships an MCP server — it relies on the `freelance` CLI being on PATH. Team members who install only the plugin (not the npm package) hit `freelance: command not found` on every skill-directed invocation. This release updates `plugins/freelance/hooks/nudge.mjs` to:  - Read the plugin version from `plugin.json` - Probe `freelance --version` - Emit a `systemMe |
| `v1.3.3` | 2026-04-17 | High | Plugin-only patch. Server code is unchanged from 1.3.2 — this release exists to propagate the `.mcp.json` pinning mechanism to users whose `/plugin update` was silently no-op'ing on stale npx cache entries.  ### Changed  - **Plugin `.mcp.json` now pins an exact `freelance-mcp` version** instead of the `^1` range. Caught by a field report after 1.3.2: npx keys its `_npx/<hash>` cache on the raw spec string, so `freelance-mcp@^1` reuses whatever 1.x is already cached and never re-resolves against |
| `v1.3.2` | 2026-04-17 | High | Hotfix release for two regressions shipped in [v1.3.1](https://github.com/duct-tape-and-markdown/freelance/releases/tag/v1.3.1).  ## Fixed  - **Plugin `.mcp.json` launcher ([#70](https://github.com/duct-tape-and-markdown/freelance/pull/70))** — 1.3.1 shipped with hardcoded author-machine dev paths instead of the `npx -y freelance-mcp@^1 mcp` launcher. Any fresh install on a different machine failed to start, and existing installs stayed pinned to whatever `freelance-mcp` npx resolved under 1.3.0 |
| `v1.3.1` | 2026-04-17 | High | The memory-architecture port. Pushed memory intelligence out of the agent's round-trip path and into the traversal layer, driven by 11 ablation runs against a controlled fixture. Design intent captured in [`docs/memory-intent.md`](docs/memory-intent.md); empirical basis in [`experiments/FINDINGS.md`](experiments/FINDINGS.md).  ## Highlights  ### Added - **Four new built-in onEnter hooks**: `memory_search`, `memory_related`, `memory_inspect`, `memory_by_source`. `memory_by_source` takes `paths: s |
| `v1.3.0` | 2026-04-14 | High | ## What's Changed * Restrict memory write tools to active memory workflow traversals by @Jwcjwc12 in https://github.com/duct-tape-and-markdown/freelance/pull/43 * Codebase cleanup: dead code, docs drift, consistency by @Jwcjwc12 in https://github.com/duct-tape-and-markdown/freelance/pull/44 * 1.3.0: architectural consolidation release by @Jwcjwc12 in https://github.com/duct-tape-and-markdown/freelance/pull/50 * 1.3.0: onEnter hooks, async engine, composition root, flat layout by @Jwcjwc12 in htt |
| `v1.3.0-beta.0` | 2026-04-13 | Medium | First beta of the 1.3.0 consolidation release. Publishes under the `beta` npm dist-tag — `@latest` stays on 1.2.1 until this bakes.  ## Install  ```bash npx freelance-mcp@beta mcp # or pin explicitly npx freelance-mcp@1.3.0-beta.0 mcp ```  Plugin users on `freelance-mcp@^1` are **not** auto-upgraded — npm semver ranges skip pre-release versions by default.  ## What's in 1.3.0  See the full [CHANGELOG entry](https://github.com/duct-tape-and-markdown/freelance/blob/main/CHANGELOG.md#130---2026-04- |
| `v1.2.1` | 2026-04-11 | Medium | ### Fixed  - **Memory enabled-by-default** — Memory gate checked `enabled && db` instead of `enabled !== false && db`, preventing zero-config memory activation when `memory.enabled` was unset  ### Changed  - **`memory_register_source` accepts arrays** — `file_path` parameter now accepts a single path or an array of paths, reducing round-trips during compilation workflows |
| `v1.2.0` | 2026-04-10 | Medium | ## Unified configuration system  Introduces `config.yml` + `config.local.yml` — a structured, layered config surface for Freelance.  ### New - **`freelance config show`** — display resolved configuration with sources - **`freelance config set-local <key> <value>`** — modify `config.local.yml` programmatically (for plugin hooks) - **`config.local.yml`** — gitignored, machine-specific overrides layered over committed `config.yml` - **`workflows:` config key** — declare additional workflow director |
| `v1.1.3` | 2026-04-10 | Medium | ### Fixes  - **Session-start hook**: called nonexistent `inspect --active --oneline` — now calls `status` - **Hook idempotency**: dedup marker didn't match the actual command, causing duplicates on re-init - **Shell completions**: all three (bash/zsh/fish) referenced removed `traversals` subgroup — rewritten for current CLI - **CONTRIBUTING.md**: wrong package name (`npx freelance` → `npx freelance-mcp`) - **Tests**: fixed stale mock (`INIT_DEFAULTS` missing `hooks`) and assertion (`validate` mi |
| `v1.1.2` | 2026-04-10 | Medium | ## Changes  - Fix publish workflow authentication for npm trusted publishing - CLI parity with all 21 MCP tools - Memory: collections, entity kinds, graph navigation, FTS triggers - Enable memory by default with --memory-dir and --no-memory flags - Fix CLI self-references in hooks, completions, and docs - Fix missing better-sqlite3 dependency for npx installs |

## Citation

- HTML: https://www.freshcrate.ai/projects/freelance
- Markdown: https://www.freshcrate.ai/projects/freelance.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/freelance/deps

_Generated by freshcrate.ai. Indexes github releases for AI-agent ecosystem packages._