Create a new Component entity.

A Component is any coherent unit of functionality that you hold context about: an internal subsystem, an external service, an API, a database, a library, or a tool. The kind tag lets you filter later.

Create a new Repo entity.

Repos hold long-lived facts about a codebase: style, testing, layout, local-dev setup, conventions. A repo optionally belongs to a parent Component (e.g. gateway-proxy-repo -> component:api-gateway).

Create a new Task entity.

Tasks are transient units of work (a feature, a bug, an investigation) that compose context by linking specific Component/Repo/Governance refs via link_task. Scaffolded subtopics: goal, plan, notes.

Create a new Governance entity — a reusable guideline.

Governance entities hold cross-cutting rules that apply to multiple components/repos/tasks: security policies, API design standards, branding guidelines, user preferences. Any other entity can reference them via governance: [...] in its frontmatter or via add_governance.

When assembling a task pack, governance refs cascade: the task's own governance + governance attached to each linked component/repo + parent components of linked repos. All deduped.

Scaffolded subtopics: overview, rules.

List all Components, optionally filtered by kind.

List all Repos.

List all Tasks.

List all Governance entities.

Delete an entity and ALL its subtopics. Destructive.

Also cleans up: aliases, task_links referencing this entity, governance links, uses-graph edges, and nullifies repo->component parent pointers.

Requires an entity-level ref (no subtopic).

Add a short nickname for an entity. Globally unique.

Example: add_alias("component:api-gateway", "gw") — then resolve_ref("gw") returns the component.

Remove an alias from an entity.

Resolve a fuzzy query ("the gateway", "gw", "auth-gw") to candidate refs.

Checks exact slug, exact alias, and case-insensitive name substring. Returns ranked candidates [{ref, source, score}] — call this before writing if the user refers to something by nickname or description.

Read the current context for an entity or a single subtopic.

Accepts an entity ref ("component:api-gateway") or a subtopic ref ("component:api-gateway/auth"). For entity refs, returns the meta + all subtopics.

Create or overwrite a subtopic's full content.

Requires a subtopic ref. Parent entity must already exist. Clears any previously stored source_url/source_name when content is overwritten without source metadata.

Append content to a subtopic, creating it if missing.

Separates appended content from existing with a blank line.

Delete a single subtopic. Parent entity is preserved.

Store content fetched from an external source as a subtopic.

Use this after another MCP tool (e.g. an Atlassian MCP for Confluence) returns page content — ContextForge then owns it as a snapshot with source tracking. source_fetched_at is set to now automatically.

Return the source_url for a subtopic so the caller can re-fetch.

ContextForge does NOT fetch. The caller (LLM) uses another MCP tool or HTTP fetcher to retrieve fresh content, then calls import_content again with the same ref.

List imported subtopics whose source_fetched_at is older than a cutoff.

Wire refs (component/repo/governance, optionally with subtopic) into a task.

Subtopic-level refs keep packs focused. Governance refs attached here also cascade to the assembled pack; governance attached to linked components/repos cascades automatically too.

Remove refs from a task's link list. Idempotent.

Assemble the full context pack for a task.

Returns the task's own meta+subtopics, all resolved linked refs, and a deduplicated governance section. If include_always is True (default), refs from config.json always_include are merged in.

When focus is True (default), entity-level refs with more than per_entity_top_k subtopics are FTS-narrowed against the task's description + own notes — only the top-K most relevant subtopics are included; the rest are returned in dropped for on-demand pull via get_subtopic / get_context. Subtopic-level refs (component:foo/bar) bypass narrowing.

Propose candidate refs to link into a task.

Walks the uses graph from the anchors (or existing links if anchors is None), collects components within depth hops, FTS-scores each candidate's subtopics against the task's description + notes, and returns top-K suggestions that aren't already linked.

Attach a governance ref to a component/repo/task.

The governance content will be included in any task pack that touches this entity (directly via link_task, or via parent-component cascade for repos). Cannot attach governance to another governance entity.

Detach a governance ref from an entity.

Attach a reference to an external tracking system (Jira, GitHub, etc.).

ContextForge does not fetch these — it just stores pointers. Use a separate MCP server (Atlassian, GitHub, etc.) to retrieve current state.

Detach an external reference from a task.

Full-text search (SQLite FTS5) across all subtopic content.

Return the current ContextForge config (always_include, workspaces).

Add a ref to the always_include list.

Any ref in this list is automatically included in every task pack. Typical use: a personal-prefs governance entity you want everywhere.

Remove a ref from the always_include list.

Associate a local workspace path with a repo slug.

Once bound, get_current_workspace(path) returns the repo slug so the LLM can auto-select relevant context when you're working in that dir.

The MCP client's Roots capability is the canonical source of the current workspace path; this tool expects that path passed in.

Remove a workspace→repo binding.

Resolve a workspace path to its bound repo (and parent component, if any).

Rebuild the SQLite + FTS5 index from markdown files on disk.

Use after manual edits on disk, or if the index seems stale. Filesystem is the source of truth.

Return the most recent lines from the persistent usage/debug log.

The log at ~/.contextforge/logs/contextforge.log (rotating) captures tool invocations, pack assemblies (with dropped counts, sizes, timings), entity creates, links, governance attachments, resolves, suggestions, context writes, and workspace binds. This is the primary signal for understanding real usage and tuning focus/governance behavior.