Forgein

The portable context layer for AI coding assistants. Write your context once — every tool you use gets it.

→ forgein.ai · app.forgein.ai · github.com/forgeinai/forgein

---

Install

curl -fsSL https://raw.githubusercontent.com/forgeinai/forgein/main/install.sh | bash

One file drops into ~/.claude/commands/forgein.md. Open a new Claude Code session — /forgein appears immediately. No server dependency. Works offline.

---

What it does

Local (zero server, MIT, free forever):

• /forgein mem — manage memory files across Claude sessions
• /forgein sec — heuristic security scan on staged git changes
• /forgein optimize — discover and install skills matched to your workflow

Cloud sync (free account at app.forgein.ai):

• /forgein auth — connect your local CLI to your forgein account
• /forgein mem sync — push your memory files to the cloud
• /forgein export <target> — write your context into any AI tool's native format

Once synced, every adapter below stays current automatically after every mem sync.

---

Adapters — 7 tools, one context store

Adapter	What it writes	How
Claude Code	Reads your memory files via the /forgein skill — run /forgein mem sync to push, no auto-injection	/forgein mem sync
MCP Server	JSON-RPC 2.0 over stateless HTTP, auto-discovered at /.well-known/mcp	api.forgein.ai/api/adapters/mcp
Cursor	.cursorrules (or ~/.cursor/rules globally)	/forgein export cursor
Windsurf	.windsurfrules (or Cascade global memory)	/forgein export windsurf
GitHub Copilot	.github/copilot-instructions.md	/forgein export copilot
ChatGPT	Custom Instructions (two-field format)	/forgein export chatgpt
Gemini	Gems system prompt	/forgein export gemini

All 7 adapters are free. None are gated to Pro.

The MCP adapter is protocol-native — any MCP-compatible client (Claude Desktop, Cursor, Windsurf Cascade) can connect directly without the CLI.

---

Commands

/forgein auth                    Authenticate CLI with your forgein account

/forgein mem                     List all memories (default)
/forgein mem list                List memories grouped by type
/forgein mem search <query>      Search memory bodies
/forgein mem add <type> <text>   Add a new memory
/forgein mem prune               Remove stale memories interactively
/forgein mem audit               Check index for structural issues
/forgein mem sync                Sync memory files with forgein cloud

/forgein export cursor           Write context to .cursorrules
/forgein export windsurf         Write context to .windsurfrules
/forgein export copilot          Write context to .github/copilot-instructions.md
/forgein export chatgpt          Format context as ChatGPT Custom Instructions
/forgein export gemini           Format context as a Gemini Gem system prompt

/forgein sec                     Security check on staged git changes
/forgein sec <path>              Security check on a file or directory

/forgein optimize                Discover and install skills for your workflow

---

How it works

Cloud sync flow

/forgein auth
  → checks ~/.config/forgein/token
  → if missing or stale: prompts user to create token at app.forgein.ai/tokens
  → stores token at ~/.config/forgein/token (chmod 600)

/forgein mem sync
  → computes sha256 of each local memory file
  → diffs against cloud manifest from api.forgein.ai/api/memory/files
  → pushes changed files, pulls files added from another machine
  → auto-runs /forgein export for any adapter files already present in project

/forgein export cursor
  → reads token from ~/.config/forgein/token
  → calls api.forgein.ai/api/adapters/cursor
  → writes response to .cursorrules in project root

/forgein optimize — algorithm

1. FETCH REGISTRY
   gh api repos/forgeinai/forgein/contents/registry.json | base64 -d
   → fallback: WebFetch raw.githubusercontent.com

2. INVENTORY INSTALLED
   ls ~/.claude/commands/
   → set of already-installed skill names (exclude from results)

3. GATHER CONTEXT SIGNALS
   cat ~/.claude/CLAUDE.md          (global instructions)
   cat CLAUDE.md                    (project instructions)
   find ~/.claude/projects -name MEMORY.md | xargs cat  (memory index)
   git log --oneline -20            (recent commit topics)
   → single context string

4. SCORE SKILLS (word-boundary matching)
   for each skill not installed:
     score = 0
     for term in (skill.signals + skill.tags):
       if term matches as a whole word in context (case-insensitive):
         score += 1
   
   Whole-word rule: char before and after match must be non-alphanumeric.
   "pr" does NOT match "sprint". "git" does NOT match "digital".

5. RANK + RECOMMEND
   sort by score desc → take top 5
   show: skill name, score, description, matched terms

6. INTERACTIVE INSTALL
   default: Enter = install all
   or pick by number: "1,3"
   or "none" to cancel
   
   install: gh api .../contents/<file> | base64 -d → write to ~/.claude/commands/

---

/forgein mem — architecture

Claude Code's auto-memory system stores context across sessions as markdown files. MEMORY.md is the index; each linked file is one memory with frontmatter:

---
name: feedback-commits
description: Commit message rules — no Claude/AI attribution
metadata:
  type: feedback        # user | feedback | project | reference
---

Commit messages must not mention Claude, AI, or any collaboration.

**Why:** commits must appear as the user's own organic work.
**How to apply:** never add Co-Authored-By lines. Write messages in first person.

Operations:

Subcommand	What it does
list	Read MEMORY.md, fetch each file's type from frontmatter, group and display
search <q>	Read all linked files, return whole-word matches in body
add <type> <content>	Write new file with frontmatter, append pointer to MEMORY.md
prune	For each memory, verify referenced artifacts still exist (PRs, files, functions). Flag stale.
audit	Structural checks: broken links, duplicates, missing frontmatter, lines > 150 chars
sync	Push/pull from forgein cloud. Requires /forgein auth first.

Memory types:

• user — who the user is, expertise, working style
• feedback — how Claude should behave (corrections AND confirmed approaches)
• project — active work, goals, deadlines
• reference — where to find things (Linear boards, dashboards, docs)

---

/forgein sec — scan algorithm

1. GET CODE
   git diff --staged          (default)
   <path>                     (if argument given)
   
   If staged diff is empty → ask user for a path. Never silently scan.

2. SCAN 8 VULNERABILITY CLASSES
   
   Class              Severity  What to look for
   ─────────────────────────────────────────────────────────────────
   Secrets            critical  Long string literals in key/secret/token vars
   Command injection  critical  User input in subprocess/eval/shell=True
   SQL injection      high      User input concatenated into SQL strings
   Path traversal     high      User input in open()/join() without realpath
   SSRF               high      User-controlled URLs fetched server-side
   XSS                medium    User input in innerHTML/unescaped templates
   Insecure deser.    medium    pickle.loads / yaml.load / eval on external data
   Hardcoded creds    medium    Literal passwords/tokens in source or config

3. OUTPUT
   Sort: critical → high → medium → low
   Each finding: severity, file:line, class, snippet (≤80 chars), attack scenario
   
   If no findings: "✓ Clean"
   Always: remind user to run a real SAST tool for production

---

Registry format

registry.json is the skill index. Each entry:

{
  "id": "commit",
  "command": "commit",
  "name": "Smart Commit",
  "description": "Generates conventional commit messages from staged changes.",
  "tags": ["git", "productivity", "conventional commits"],
  "signals": ["commits", "commit messages", "changelog", "semantic versioning"],
  "author": "forgein-ai",
  "version": "1.0.0",
  "file": "skills/commit.md",
  "install_as": "commit.md"
}

• tags — broad categories (used in scoring)
• signals — specific phrases that indicate a user needs this skill (used in scoring)
• file — path to the skill .md file in this repo
• install_as — filename written to ~/.claude/commands/

Scoring weight: tags and signals are treated equally. A skill with 3 tag matches and 2 signal matches scores 5.

---

Skills in the registry

Skill	Command	Description
Forgein	/forgein	Auth, memory sync, multi-tool export, security check, skill optimizer
Vibe Sec	/sec	Standalone security check
Claude Mem	/mem	Standalone memory manager
Code Review	/review	Bugs, perf, security, style — parallel passes
Smart Commit	/commit	Conventional commit messages from staged diff
Standup	/standup	Daily standup from git log + open PRs
PR Monitor	/pr-monitor	CI status across all open PRs
Test Gen	/test-gen	Generate tests — auto-detects pytest/jest/go
Explain Codebase	/explain	Architecture map for new contributors
Changelog	/changelog	CHANGELOG.md from git log between tags

---

Submit a skill

1. Add your .md file to skills/
2. Add an entry to registry.json
3. Open a PR

Skill file format: A markdown file with a YAML frontmatter description field. The body is instructions to Claude — what to do, what tools to use, what output to produce. Written in second person imperative. See any existing skill file as a template.

Good signals are specific phrases that appear in someone's CLAUDE.md or git log when they need your skill. Bad signals are things everyone has ("code", "files", "project").

---

How Claude skills work

Skills are markdown files in ~/.claude/commands/. When you type /forgein, Claude reads forgein.md and follows its instructions — using your local shell, files, and APIs. No server. No telemetry. Runs entirely in your Claude Code session.

The skill file is the product. It tells Claude: what the user wants, what tools to call, what output format to use.

---

Free vs. Pro

	Free	Pro ($4.99/mo)	Team
All 7 adapters + MCP server	✓	✓	✓
Memory projects	3	Unlimited	Unlimited
Files per project	100	Unlimited	Unlimited
Contexts (Work/Home/Family)	Work only	All 3	All 3
Private skills	—	✓	✓
Team memory sharing	—	—	✓
Org baseline templates	—	—	✓
AI adoption analytics	—	—	✓
API tokens	1	5	Unlimited

The portability mechanism — every adapter, the full MCP server — is free. Pro gates scale (more projects, more contexts). Team gates organizational features.

---

License

MIT — CLI and skill files in this repo (forgeinai/forgein)

The hosted sync service at app.forgein.ai is separate and not MIT-licensed.