Ferrow

A knowledge vault that acts — your notes, your AI agents, on your machine, yours.

Ferrow keeps your notes as plain Markdown files in a folder you own, connects them to any model you like (your API key, or a model running on your own computer), and lets agents read and write that vault under rules you set. Every change an agent makes is logged and can be undone with one command.

It runs in the terminal today. There is no account to create before it works, and nothing is uploaded anywhere.

npm install -g @ferrow/ferrow
ferrow vault init
ferrow note inbox/today.md "the thing I just learned"
ferrow search learned

The name is scoped — @ferrow/ferrow — because npm reserves bare names that look like existing packages; the command it installs is still just ferrow. The rest of this file is written as if you have run it. Every way in, including a checkable tarball and the macOS, Windows and Linux builds, comes with a sha256.

New to the terminal? Read QUICKSTART.md instead — same thing, five minutes, with every screen shown.

Bought Ferrow on the website? One line switches this computer on:

ferrow activate <your key>

Your key looks like ferrow_ followed by a long string, and it is shown on the page you land on after paying. The same command takes the cs_… checkout reference or the whole web address of that page, so whatever you copied is the right thing. The key also stays in Ferrow under Settings → Account, where you can reveal and copy it again for a second machine.

60 seconds

Node 20 or newer is the only requirement.

1. Connect a model. On a Ferrow plan, this step is already done — models are included, so there is no key to get:

ferrow activate <your key>   # bought on the website? switch this machine on
ferrow chat auto "hello"     # …and that is the whole command

Otherwise, either a paid API key:

ferrow providers          # the ones it knows, and where to get a key
ferrow connect openai     # asks for the key, tests it, stores it in your keychain

…or a model already running on your machine:

ferrow detect             # looks for Ollama, LM Studio, Jan, llama.cpp, vLLM, GPT4All

2. Make the vault.

ferrow vault init         # creates ~/FerrowVault and its memory/ folder

3. Use it.

ferrow chat auto "what should I read about vector search?"   # on a plan: no provider, no key
ferrow chat openai gpt-4o-mini "same question"               # with your own key: name the provider
ferrow note inbox/today.md "Ferrow keeps notes as files I can read without it."
ferrow remember drinks-tea "I drink tea, not coffee"
ferrow search notes
ferrow run summarize "condense my inbox notes into three bullets"
ferrow council "should I take the contract or keep freelancing?"
ferrow ui                 # the same vault in your browser, on this machine only

ferrow with no arguments prints where you are and what to do next; ferrow help prints the full command list, grouped. ferrow log shows everything an agent has changed, newest first; ferrow log revert <id> undoes any one of them.

What it does

The vault. A folder of Markdown files. Wikilinks and backlinks, full-text search that shows you the line it matched on, and a memory/ folder of durable facts (remember / recall / forget) that every agent reads before it starts. Nothing is in a database; if you delete Ferrow tomorrow your notes are still ordinary files in an ordinary folder.

Any model, including theirs. One internal bus speaks the OpenAI chat-completions shape, so anything with an OpenAI-compatible endpoint works — including every local runtime, and including xAI's Grok — and native adapters for Anthropic and Gemini recover the features their compatibility layers drop. OpenAI, Anthropic, Google, OpenRouter, xAI, or a model running on your own machine: it is a dropdown, not a migration. Keys go into the macOS keychain, or into ~/.ferrow/keys.json at mode 0600 if there is no keychain. They are never printed, never logged, and never sent anywhere except the provider they belong to.

Teammates. A teammate is a named worker with a published job description and a written limit on what it may touch, decided before it starts rather than asked for afterwards. ferrow skills shows you every one of them and exactly what each is allowed to reach.

Sites with no API. ferrow browser connect <site> opens the site in a browser Ferrow keeps on your own disk, in its own profile, and waits while you sign in. Ferrow never sees the password and never types it. ferrow browser sites lists everything you connected; ferrow browser revoke <site> clears it. Connecting a site grants an agent nothing: a teammate reaches a host only if its own SKILL.md names that host, checked on every navigation and on every request the page makes.

The browser it drives is one Ferrow downloads and pins, never your Chrome, and it looks after itself: a page cannot download files to your disk, a session nobody has used for five minutes is closed (a sign-in window you are looking at is never closed under you), and a browser that crashes says so instead of leaving a spinner. ferrow browser health answers "is this working, what is open, what is stuck" in one screen — and ferrow browser close clears anything a crash left behind, without touching the profiles your sign-ins live in.

If a site shows a verification wall instead of its content, Ferrow says so in plain words and stops there. It does not work around a check meant to stop a machine — you open the site yourself with ferrow browser connect, pass the check by hand, and the session stays in Ferrow's own profile on your own disk.

Agents with contracts. A skill is one folder with a SKILL.md inside: the frontmatter states what it may touch (which paths, whether it may write, whether it needs the shell or the network, whether it must ask first), and the body is what it is told to do. The executor enforces the frontmatter — a skill that never declared write access cannot write, however it is prompted.

The Council. Runs on your machine, on your own model, whether that is an API key or a local runtime; nothing about it is sent to Ferrow. ferrow council "<question>" puts a decision to a set of personas — Strategist, Skeptic, Builder, User-Advocate, Realist — and returns their disagreement, not an average.

Projects. Each project is its own vault: separate notes, memory, skills, and history. Your personal memory (~/Ferrow/Personal) is read by all of them, so who you are never has to be re-taught.

Import. ferrow import conversations.json reads a ChatGPT or Claude export, or a .jsonl of messages, and files it into the vault. Add --dry-run to see exactly what it would write first. The parsing happens on your machine; nothing is uploaded.

Your agents can use it: ferrow serve-mcp

Ferrow is also an MCP server, so the agent you already use — Claude Code, Claude Desktop, or anything else that speaks the Model Context Protocol — can read your vault instead of being told about it. One line:

claude mcp add ferrow -- ferrow serve-mcp

Then ask your agent something about your own notes. It searches and reads them itself.

The demo, end to end, in under five minutes. Nothing here needs us present:

ferrow note inbox/tuesday.md "Tuesday: decided to keep the annual plan and drop the pilot"
claude mcp add ferrow -- ferrow serve-mcp
ferrow serve-mcp --check          # exactly what a client will see, before one connects

Now ask your existing agent "what did I decide last Tuesday?" — their agent, our answer, your files. Pass: it quotes the note back. Fail: it does not, and --check told you why before you connected.

It starts read-only: vault_search, vault_read, memory_recall and nothing more. Writing, memory changes and skills are off until you turn them on in ~/.ferrow/serve-mcp.json, and a refusal names the tool, the group and the exact edit that would allow it. ferrow serve-mcp --check prints precisely what a connecting client will see, before you connect one.

Full setup — including a script you can paste into an agent and have it do the whole install — is in docs/SETUP-VIA-AGENT.md.

Check it yourself

Every claim above is something you can run on your own machine, with an artifact at the end you open in a program that is not ours. Half of them are things Ferrow refuses to do, which are the ones worth running: anyone can demo a success, and nobody fakes a refusal that names its own rule.

| What is claimed | What you type | What you should see | |---|---|---| | Teammates have published limits | ferrow skills, then open that skill's SKILL.md | The job description and the paths, in plain text you can edit | | It stops itself, and says which clause stopped it | ferrow run <skill> "<something outside its scope>" | A refusal naming the rule, e.g. denied by write_scope | | Silence is a denial, not consent | ferrow approvals, then wait past the TTL | It lists as denied. There is no setting that makes silence a yes | | The sign-in is yours, and reversible | ferrow browser connect github.com, then ferrow browser sites, then ferrow browser revoke github.com | A plain sites.json you can read, and a row that only disappears once the sign-in is actually cleared | | A teammate cannot reach a site you did not allow | run a skill against a host its SKILL.md does not name | Refused, naming the allowlist | | The bill is predictable | ferrow spendcap --set 1.00, then try to spend two | The meter refuses. Same number in the terminal and on screen | | Any model, including theirs | switch provider in ferrow connect, run the same job | Two runs, same output shape | | Your existing agent can adopt it | the serve-mcp demo above | Their agent, our answer, your files |

A demo that has never been run since it was written is a claim again, so these are run before each release. The program these come from is docs/PARITY-PLUS.md.

Privacy, in plain words

• Your notes stay on your disk. The vault is a folder. Ferrow reads and writes files in it. There is no background sync, no cloud copy, and no telemetry — nothing reports your usage, your file names, your errors, or the fact that you launched it.
• Every network call Ferrow makes, in full. Working with your vault — note, search, log, undo, memory — makes none at all. Beyond that there are exactly five, and the first four happen only because you ran the command that makes them:
  1. The model provider you connected, when you ask Ferrow to think. On Private and Free that call goes from your machine straight to OpenAI/Anthropic/Google/OpenRouter or to a local runtime, on your key. Ferrow's servers are not in the path.
  2. api.ferrow.ai, the account and billing server, when you run activate, subscribe, billing, unsubscribe, spendcap and their kin. It sees an email, a subscription id and a plan. It never sees a vault, a note, a file name, or a provider key.
  3. api.ferrow.ai again, on Managed only, because on Managed we make the model call: the text of the request and the model's answer pass through Ferrow's Worker, and the meter records model, token counts, cost and a request id so the spend cap can be a hard stop. A completed answer is held against its request id for about 24 hours so a retry replays instead of charging the provider twice. That is the one thing on Managed we hold rather than pass through.
  4. The relay, if you pair devices — see the relay bullet below.
  5. ferrow.ai/dl/latest.json, and only when you run ferrow doctor, to say whether a newer version exists. It is a plain GET of a static file; it sends nothing about you, and it is the only outbound call in the product that is not about a thing you explicitly asked Ferrow to do.
• Nothing here is "no server component". Ferrow used to say that, and it was wrong. What runs on your machine: the CLI, the vault, the agents, the skills, the Council, ferrow ui, and ferrow hub. What runs on ours: one Cloudflare Worker at api.ferrow.ai doing accounts, billing, the Managed gateway, and the relay. That is the whole server side; there is no third party in it.
• Your keys stay in your keychain. Stored via security(1) on macOS, or a 0600 file otherwise. They go to the provider's API and nowhere else.
• The browser UI is local only. ferrow ui binds to 127.0.0.1, so nothing off your machine can reach it, and its API requires a random token minted at boot and destroyed when you stop the process. Note honestly: any program running as you on this machine can load that page and read the token from it. The token stops a website you happen to be visiting from reading your vault over localhost; it is not a defence against software you have already installed.
• What the relay sees, and it is built. Pair a phone or a browser to the machine running ferrow hub and the relay — a Durable Object on the same Worker — passes messages between your own devices. What crosses it is sealed by the devices at each end; the relay carries blobs it cannot read. It does not carry your vault, your notes, or your keys, which stay on the hub machine. Nothing crossing it is written to disk, and a bounded window of the most recent sealed frames is held in memory so a phone that drops its connection can resume without a gap. No pairing, no relay: it is inert until you run ferrow hub.
• Cards never reach us. Checkout happens on Stripe's own pages. What the Worker receives from Stripe is a checkout session id, a subscription id, the plan, and the email you paid with. Your card number is not something we could show you if you asked.
• The full version of this is ferrow.ai/privacy, which lists every field the account record holds and how long each one is kept. If it and this section ever disagree, that page is the authority and this one is the bug.

Editions and price

There are three rows, and the first one never expires.

| | Free | Private (BYO) | Managed | |---|---|---|---| | Price | $0, no card, no account | $20/month, or $180/year | same subscription, plus usage | | Models | your own API keys, or a local model | your own API keys, or local models | prebuilt, billed through Ferrow | | Vault, notes, search, change log, undo | yes | yes | yes | | Agents, skills, the Council, ferrow ui | yes, on your own keys | yes | yes | | Managed model calls (Ferrow's keys) | — | — | yes | | Schedules that run with this machine off | — | — | yes | | Sync across your devices (relay + hub) | — | yes | yes | | Usage cost | whatever your provider charges you | whatever your provider charges you | you pay for what you use — itemized per call | | Cap | n/a | n/a | a hard limit you set — ferrow spendcap <amount> | | Trial | n/a — it is already free | 3 days, card required, not charged for 3 days | — |

Free is not a trial. Everything Ferrow does on this machine is free forever and needs no account: the vault, the search, the change log and its undo, the agents, the skills, the Council, the local browser UI — all of it, running against a model you already pay for or one running on your own hardware. ferrow billing on an unpaid machine prints exactly that, in those words.

A plan buys the three things that cannot happen on your machine alone: Ferrow doing the thinking on its own keys, jobs that run while your machine is off, and your notes on more than one device.

The 3-day trial is a separate thing from the free tier, and it is Private only, because Managed spends real money on your behalf from the first call. Checkout collects a card and does not charge it during the trial; cancel inside the three days with ferrow unsubscribe and nothing is charged at all.

The Managed cap is a stop, not a warning. Ferrow does not charge past the number you set. Check it any time with ferrow spendcap status; it shows the cap, what has been spent, and what is left.

ferrow unsubscribe cancels in one command, with no retention flow. You keep the period you have already paid for.

Everything above — the vault, agents, skills, the Council, the UI, import — works with your own keys. The subscription pays for the orchestration layer and, in Managed, for not having to hold five API accounts.

Status, honestly

Ferrow is pre-1.0 and has not had its first outside user yet. What is real:

• Terminal: working. The suite is 2400+ tests, all green (node --test prints the live number). This is still the centre of the product.
• Local browser UI (ferrow ui): working, read-and-revert. It shows the vault and the change log; it is not yet a full editor.
• Web client: built. Relay pairing, vault browsing, streaming replies, and dark parity with the terminal. It is the one client — clients/ are windows around it, not reimplementations.
• Relay + hub: built. Device pairing and sync work.
• Voice (ferrow voice) and scheduled agents (ferrow schedule): built.
• Workflow kernel and the Council: built. A Council runs entirely on your own machine, on the model you connected — nothing about it reaches Ferrow. On Managed it runs on Ferrow's keys instead, which is what that plan is.
• Managed metering and the hard spend cap: built.
• Desktop (Tauri), iOS, Android: CI produces three-OS desktop bundles and an Android AAB on every version tag; the dmg/exe/deb on ferrow.ai/download are real artifacts with published sha256s. iOS is not on TestFlight: the app is built and signed, and the one thing in the way is the App Store Connect app record, which Apple's API refuses to create (POST /v1/apps → "The resource 'apps' does not allow 'CREATE'") — it is made in the UI or not at all. No tester has the iOS build, and no client is in a public store yet. See clients/README.md, which is the authority on this row.
• Billing: live. The Worker is deployed, the Stripe endpoint is live, and the full chain — checkout, webhook, entitlement, activation — has settled a real purchase. Transactional email (verify, password reset) sends via a verified domain.
• Published: @ferrow/ferrow is on npm (npm i -g @ferrow/ferrow), and the same tarball is served from ferrow.ai/download with its sha256. ferrow.ai and app.ferrow.ai are live.

If a feature is not in the list above, assume it does not exist yet. This section is the one place in the project allowed to talk about the future, and it will be edited down as things ship rather than expanded.

• Product: ferrow.ai · Owner: Ruzylo Holdings
• Support: [email protected] · https://ferrow.ai/support
• Ferrow is not Danylo (a separate private assistant) and shares no code with it.