forgein

API Reference

The forgein API exposes your memory files as context blocks for every AI tool. All endpoints use Bearer token authentication. Tokens start with fg_ and are created at app.forgein.ai/tokens.

Base URL: https://api.forgein.ai·All endpoints: HTTPS only

Authentication

Every API request must include an Authorization header with a Bearer token. Tokens are scoped to a single user account. Create and revoke them from the dashboard.

Authorization: Bearer fg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Requests without a valid token return 401 Unauthorized. Rate limits apply per token: 300 req/min for API routes, 30 req/min for AI endpoints, 15 req/min for auth endpoints.

Adapters

Adapter endpoints return your context formatted for a specific tool. All accept two optional query parameters: projectPath (include project-specific files) and context (override active context: work | home | family).

GET/api/adapters/claude-code

Claude Code context

Returns your context as newline-separated markdown sections. The CLI injects this directly into the system prompt via CLAUDE.md or memory files.

NameTypeDescription

projectPathstringThe forgein project path for the current repo (e.g. -Users-alice-api). Includes project-specific memory files when provided.

contextstringOverride the active context. One of: work (default), home, family.

curl -s "https://api.forgein.ai/api/adapters/claude-code?projectPath=-Users-alice-api" \
  -H "Authorization: Bearer fg_..."

GET/api/adapters/chatgpt

ChatGPT Custom Instructions

Returns a formatted block ready to paste into ChatGPT → Settings → Custom Instructions.

NameTypeDescription

projectPathstringThe forgein project path for the current repo (e.g. -Users-alice-api). Includes project-specific memory files when provided.

contextstringOverride the active context. One of: work (default), home, family.

curl -s "https://api.forgein.ai/api/adapters/chatgpt?projectPath=-Users-alice-api" \
  -H "Authorization: Bearer fg_..."

GET/api/adapters/copilot

GitHub Copilot instructions

Returns the full content for `.github/copilot-instructions.md` scoped to the requested project.

NameTypeDescription

projectPathstringThe forgein project path for the current repo (e.g. -Users-alice-api). Includes project-specific memory files when provided.

contextstringOverride the active context. One of: work (default), home, family.

curl -s "https://api.forgein.ai/api/adapters/copilot?projectPath=-Users-alice-api" \
  -H "Authorization: Bearer fg_..."

GET/api/adapters/gemini

Gemini system prompt

Returns a formatted system prompt for Gemini Gems. Paste into the Gem configuration.

NameTypeDescription

projectPathstringThe forgein project path for the current repo (e.g. -Users-alice-api). Includes project-specific memory files when provided.

contextstringOverride the active context. One of: work (default), home, family.

curl -s "https://api.forgein.ai/api/adapters/gemini?projectPath=-Users-alice-api" \
  -H "Authorization: Bearer fg_..."

GET/api/adapters/cursor

Cursor rules

Returns the full content for `.cursorrules` at the repo root. Paste to apply context to Cursor AI suggestions.

NameTypeDescription

projectPathstringThe forgein project path for the current repo (e.g. -Users-alice-api). Includes project-specific memory files when provided.

contextstringOverride the active context. One of: work (default), home, family.

curl -s "https://api.forgein.ai/api/adapters/cursor?projectPath=-Users-alice-api" \
  -H "Authorization: Bearer fg_..."

GET/api/adapters/windsurf

Windsurf rules

Returns the full content for `.windsurfrules`. Paste into your repo root for Cascade to pick up.

NameTypeDescription

projectPathstringThe forgein project path for the current repo (e.g. -Users-alice-api). Includes project-specific memory files when provided.

contextstringOverride the active context. One of: work (default), home, family.

curl -s "https://api.forgein.ai/api/adapters/windsurf?projectPath=-Users-alice-api" \
  -H "Authorization: Bearer fg_..."

POST/api/adapters/mcp

MCP server (JSON-RPC 2.0)

A stateless MCP server. Each request is a JSON-RPC 2.0 envelope with a method and optional params. All 6 standard MCP methods are supported. No WebSocket or session management required.

NameTypeDescription

jsonrpcreqstringAlways "2.0".

idreqnumberRequest ID — returned verbatim in the response.

methodreqstringOne of: initialize, ping, resources/list, resources/read, prompts/list, prompts/get.

paramsobjectMethod-specific parameters. For resources/read: { uri: "forgein://context/…" }. For prompts/get: { name: "forgein-context", arguments: { projectPath?: string } }.

curl -s -X POST "https://api.forgein.ai/api/adapters/mcp" \
  -H "Authorization: Bearer fg_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "prompts/get",
    "params": {
      "name": "forgein-context",
      "arguments": { "projectPath": "-Users-alice-api" }
    }
  }'

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "messages": [{
      "role": "user",
      "content": { "type": "text", "text": "## Work Context\n..." }
    }]
  }
}

The @forgein/adapter-sdk exposes client.callMcp(method, params) which handles envelope construction and result unwrapping automatically.

GET/api/adapters/usage

Adapter usage log

Returns the 20 most recent adapter calls for the authenticated user. Useful for auditing which tools are accessing context and from which projects.

curl -s "https://api.forgein.ai/api/adapters/usage" \
  -H "Authorization: Bearer fg_..."

// Response — array of up to 20 rows
[
  {
    "adapterType": "claude-code",
    "projectPath": "-Users-alice-api",
    "createdAt": "2026-07-10T14:22:00Z"
  },
  ...
]

GET/api/adapters/usage/stats

Adapter usage stats

Returns aggregate usage statistics: per-adapter totals, 7-day and 30-day call counts, and a 14-day daily breakdown for sparkline charts.

curl -s "https://api.forgein.ai/api/adapters/usage/stats" \
  -H "Authorization: Bearer fg_..."

// Response
{
  "byAdapter": [
    { "adapterType": "claude-code", "total": "142" },
    { "adapterType": "chatgpt",     "total": "38" }
  ],
  "total7d": 24,
  "total30d": 89,
  "daily": [
    { "day": "2026-07-10", "n": 8 },
    { "day": "2026-07-09", "n": 5 }
  ]
}

Memory files

Memory files are markdown documents organized by project path. A project path is the filesystem path to your repo with / replaced by -, e.g. -Users-alice-api. Context files (personal/home/family) use special paths prefixed with __ctx_work__, __ctx_home__, etc.

GET/api/memory/files

List files

Returns all memory files for a given project path.

NameTypeDescription

projectPathreqstringThe project to list files for.

curl -s "https://api.forgein.ai/api/memory/files?projectPath=-Users-alice-api" \
  -H "Authorization: Bearer fg_..."

// Response
[
  { "filePath": "stack.md", "content": "...", "updatedAt": "2026-07-10T10:00:00Z" },
  { "filePath": "conventions.md", "content": "...", "updatedAt": "2026-07-09T08:30:00Z" }
]

GET/api/memory/files/:filePath

Read file

Returns the content of a single memory file.

NameTypeDescription

projectPathreqstringThe project the file belongs to (query param).

:filePathreqstringThe file name within the project, e.g. stack.md (URL segment).

curl -s "https://api.forgein.ai/api/memory/files/stack.md?projectPath=-Users-alice-api" \
  -H "Authorization: Bearer fg_..."

PUT/api/memory/files

Write file

Creates or overwrites a memory file. The file is immediately available to all adapter endpoints.

NameTypeDescription

projectPathreqstringThe project to write the file into.

filePathreqstringFile name, e.g. sprint.md.

contentreqstringFull markdown content of the file.

curl -s -X PUT "https://api.forgein.ai/api/memory/files" \
  -H "Authorization: Bearer fg_..." \
  -H "Content-Type: application/json" \
  -d '{ "projectPath": "-Users-alice-api", "filePath": "sprint.md", "content": "## Sprint 14\n..." }'

DELETE/api/memory/files/:filePath

Delete file

Permanently deletes a memory file. This action is irreversible.

NameTypeDescription

projectPathreqstringThe project the file belongs to (query param).

:filePathreqstringThe file name to delete (URL segment).

curl -s -X DELETE "https://api.forgein.ai/api/memory/files/sprint.md?projectPath=-Users-alice-api" \
  -H "Authorization: Bearer fg_..."

GET/api/memory/history

File history

Returns recent edit history for files in a project. Useful for auditing changes.

NameTypeDescription

projectPathreqstringThe project to fetch history for.

curl -s "https://api.forgein.ai/api/memory/history?projectPath=-Users-alice-api" \
  -H "Authorization: Bearer fg_..."

GET/api/memory/search

Search files

Full-text search across all memory files. Returns matching files with a short snippet showing the matched context.

NameTypeDescription

qreqstringSearch query — minimum 2 characters.

projectPathstringScope search to a specific project.

curl -s "https://api.forgein.ai/api/memory/search?q=deployment" \
  -H "Authorization: Bearer fg_..."

// Response
[
  {
    "projectPath": "-Users-alice-api",
    "filePath": "ops.md",
    "snippet": "…run helm upgrade --install app ./chart on every deployment…",
    "updatedAt": "2026-07-08T09:00:00Z"
  }
]

GET/api/memory/projects

List projects

Returns all distinct project paths that have at least one memory file, along with file counts and the last sync timestamp.

curl -s "https://api.forgein.ai/api/memory/projects" \
  -H "Authorization: Bearer fg_..."

// Response
[
  { "projectPath": "-Users-alice-api", "fileCount": 5, "lastSyncedAt": "2026-07-10T14:00:00Z" },
  { "projectPath": "-Users-alice-web", "fileCount": 2, "lastSyncedAt": "2026-07-09T10:00:00Z" }
]

Webhooks

Webhooks fire a signed HTTP POST to a URL you control when a memory file is saved. The event payload is signed with HMAC-SHA256 using the webhook secret and delivered in the X-Forgein-Signature header.

GET/api/webhooks

List webhooks

Returns all webhooks for the authenticated user.

curl -s "https://api.forgein.ai/api/webhooks" -H "Authorization: Bearer fg_..."

// Response
[
  {
    "id": "wh_abc123",
    "url": "https://your-server.com/hooks/forgein",
    "events": ["memory.updated"],
    "isActive": true,
    "createdAt": "2026-07-01T12:00:00Z"
  }
]

POST/api/webhooks

Create webhook

Creates a new webhook. The response includes the signing secret — store it now, it is never returned again.

NameTypeDescription

urlreqstringThe HTTPS endpoint to deliver events to.

eventsstring[]Event types to subscribe to. Defaults to ["memory.updated"].

curl -s -X POST "https://api.forgein.ai/api/webhooks" \
  -H "Authorization: Bearer fg_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.com/hooks/forgein", "events": ["memory.updated"] }'

// Response (secret returned once)
{
  "id": "wh_abc123",
  "url": "https://your-server.com/hooks/forgein",
  "events": ["memory.updated"],
  "isActive": true,
  "secret": "whsec_...",
  "createdAt": "2026-07-10T14:00:00Z"
}

PATCH/api/webhooks/:id

Toggle webhook

Enables or disables a webhook without deleting it.

NameTypeDescription

isActivereqbooleanSet to true to enable, false to disable.

curl -s -X PATCH "https://api.forgein.ai/api/webhooks/wh_abc123" \
  -H "Authorization: Bearer fg_..." \
  -H "Content-Type: application/json" \
  -d '{ "isActive": false }'

DELETE/api/webhooks/:id

Delete webhook

Permanently deletes a webhook.

curl -s -X DELETE "https://api.forgein.ai/api/webhooks/wh_abc123" \
  -H "Authorization: Bearer fg_..."

GET/api/webhooks/:id/deliveries

Delivery log

Returns the 20 most recent deliveries for a webhook, including HTTP status, latency, and the first 2 KB of the response body.

curl -s "https://api.forgein.ai/api/webhooks/wh_abc123/deliveries" \
  -H "Authorization: Bearer fg_..."

// Response
[
  {
    "id": "del_xyz",
    "event": "memory.updated",
    "responseStatus": 200,
    "responseBody": "ok",
    "durationMs": 143,
    "createdAt": "2026-07-10T14:22:00Z"
  }
]

POST/api/webhooks/:id/ping

Test ping

Sends a test memory.updated delivery to the webhook URL with "test": true in the payload and X-Forgein-Test: 1 in the headers. Records the delivery in the log and updates lastFiredAt.

curl -s -X POST "https://api.forgein.ai/api/webhooks/wh_abc123/ping" \
  -H "Authorization: Bearer fg_..."

// Response
{ "ok": true, "status": 200, "durationMs": 91 }

Event payload

When a memory file is saved, forgein sends a signed HTTP POST to each active webhook. The request body is a JSON object containing the event type and file metadata. The signature is an HMAC-SHA256 digest of the raw request body, delivered in X-Forgein-Signature.

// Headers
X-Forgein-Event: memory.updated
X-Forgein-Signature: sha256=<hmac-sha256-hex>
Content-Type: application/json
User-Agent: forgein-webhooks/1.0

// Body
{
  "event": "memory.updated",
  "filePath": "sprint.md",
  "projectPath": "-Users-alice-api",
  "sha256": "a3f1b2c4...",
  "updatedAt": "2026-07-10T14:00:00Z",
  "deliveredAt": "2026-07-10T14:00:01Z"
}

Verify the signature before processing the event to reject spoofed requests:

// Node.js signature verification
import crypto from 'crypto';

export function verifyForgeinSignature(
  rawBody: string,
  signature: string,
  secret: string,
): boolean {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

API tokens

API tokens authenticate all API requests. Free accounts can create 1 token; Pro accounts up to 10. Token values start with fg_ and are only returned at creation time.

GET/api/tokens

List tokens

Returns all tokens for the authenticated user (values are not included).

curl -s "https://api.forgein.ai/api/tokens" -H "Authorization: Bearer fg_..."

// Response
[
  { "id": "tok_abc123", "name": "laptop-claude", "lastUsedAt": "2026-07-10T09:00:00Z", "createdAt": "2026-06-01T08:00:00Z" }
]

POST/api/tokens

Create token

Creates a new API token. The token value is returned once — store it securely.

NameTypeDescription

namereqstringA human-readable label, e.g. "work-laptop".

curl -s -X POST "https://api.forgein.ai/api/tokens" \
  -H "Authorization: Bearer fg_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "work-laptop" }'

// Response (token returned once)
{ "id": "tok_abc123", "name": "work-laptop", "token": "fg_..." }

DELETE/api/tokens/:id

Revoke token

Permanently revokes a token. Any in-flight requests using the token will fail immediately.

curl -s -X DELETE "https://api.forgein.ai/api/tokens/tok_abc123" \
  -H "Authorization: Bearer fg_..."

Auto-discovery

MCP-compatible tools that support the Model Context Protocol discovery spec can fetch the forgein server URL and auth instructions automatically — no manual config required.

GET/.well-known/mcp

curl -s "https://api.forgein.ai/.well-known/mcp"

// Response
{
  "mcpServers": {
    "forgein": {
      "url": "https://api.forgein.ai/api/adapters/mcp",
      "description": "Forgein personal context server — memory files, team conventions, and project notes.",
      "authentication": {
        "type": "Bearer",
        "tokenUrl": "https://app.forgein.ai/tokens"
      }
    }
  }
}

Also available at /.well-known/mcp.json (redirects to the same endpoint).