Forgetful CLI Setup

What it does

When your agent uses it

• Installing the Forgetful CLI on a developer machine
• Connecting a CI job or headless agent to a Forgetful server with a token
• Checking that a local or remote Forgetful setup works end to end
• Scripting Forgetful calls that need JSON output and reliable exit codes

Example prompts

• “Set up the Forgetful CLI in local mode and verify it with a real call.”
• “Connect this CI job to our Forgetful server using a bearer token from the environment.”
• “Start a local Forgetful server over http on port 8020.”

Requirements

• Python with pip, or uv, to install forgetful-ai
• A Forgetful server URL and token for remote mode
• Pre-approved tools (allowed-tools): Bash(forgetful:*)

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

1. 1Curated verbs for the common paths: forgetful memory search|save|get|recent,
2. 2forgetful tools list [--category ] to discover every registry operation.
3. 3forgetful tools info for the schema.
4. 4forgetful call --args '' to invoke anything the registry has.

What it can do on your machine

Read from SKILL.md and the folder at commit 7afcbf1. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • Bash(forgetful:*)

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • uvx
  • pip

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md. Its commands use uvx and pip, which can reach the network depending on how they are called.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names these keys or tokens, usually read from environment variables:

  • FORGETFUL_TOKEN

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Forgetful CLI Setup loads about 898 tokens when it runs. Until then it costs about 97 tokens; SKILL.md has 355 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~97

When it runs · the whole SKILL.md, loaded when a task matches

~898

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NoteMentions a .env fileSKILL.md:41

  rges shell env over `~/.config/forgetful/.env`. Check state anytime with

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from ScottRBK/forgetful at commit 7afcbf1, republished under its MIT licence (© ScottRBK). 355 words, ~898 tokens.

name

forgetful-cli-setup

description

Set up the Forgetful CLI and connect from a terminal — install, local or remote mode, auth, and verification. Use when connecting a human or headless agent via shell, wiring CI with token auth, or operating a local server (serve, database selection, feature flags, re-embedding). Also covers the machine contract: --json output, exit codes, and the discovery ladder.

allowed-tools

Bash(forgetful:*)

license

MIT

disable-model-invocation

true

tags

cli, setup, auth, operations, terminal

uvx forgetful-ai --version     # ephemeral, no install
pip install forgetful-ai       # or: uv tool install forgetful-ai

forgetful tools list                          # registry categories come back
forgetful project list --json                 # one real call round-trips

© ScottRBK, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/forgetful-cli-setup of ScottRBK/forgetful.

Open the folder on GitHubat commit 7afcbf1