ContextForge

Self-hosted memory and distillation runtime for coding agents.

한국어 README · Full reference · Architecture · Operations

Current package version: 0.6.0

ContextForge keeps scoped durable memory, raw evidence, and distilled checkpoint handoffs in a self-hosted runtime. It gives Codex, Claude Code, OpenCode, Grok, Cursor CLI, and MCP clients a shared memory boundary without treating every old conversation as durable truth.

Core Model

• memory: reviewed durable facts, decisions, contracts, preferences, and runbooks.
• checkpoint: compressed recent handoff state. Verify mutable git, CI, deployment, and runtime claims against live sources.
• memory_candidate: review material produced by distillation; never durable truth until explicitly promoted.
• raw evidence: user/assistant conversation evidence that survives failed distillation.
• shared, repo, and local: explicit retrieval scopes.

ContextForge supports three storage modes:

• project-local (default): repo-bound SQLite under .contextforge/.
• local: single-machine SQLite under the user data directory.
• remote: canonical HTTP server for several agents or machines.

Do not use Git as the live backend for SQLite or raw runtime data.

What's New In 0.6.0

• A supervised candidate lifecycle worker that wakes snoozes, queues idle audits, and applies bounded stale SLA transitions, dry-run by default.
• Operation-worker freshness on /readyz plus candidate throughput, audit routing, correction, and retrieval-coverage metrics.
• Bounded pre-migration backups, cleared production dependency advisories, and a per-profile MCP surface ratchet.
• Concise agent guidance for scoped retrieval, session identity, and trust boundaries, with detailed topics available as ordinary documentation.
• Node 24 floor and better-sqlite3 13.x, whose N-API prebuilds drop 85 transitive packages.
• A CI-only ESLint gate, a core facade decomposed from 7,169 to 4,839 lines, and a test suite reorganized by topic.

See CHANGELOG.md for the complete unreleased and historical record. English and Korean release summaries are checked against the package version in CI.

Quick Start

Requirements: Node.js 24 or newer.

npm install
npm run verify
node src/cli.js dbInfo

Create synthetic repo-scoped evidence and distill it with the built-in mock provider:

export CONTEXTFORGE_STORAGE_MODE=project-local
export CONTEXTFORGE_DISTILL_PROVIDER=mock

node src/cli.js appendRaw \
  --scope repo \
  --scopeKey github.com/example/contextforge \
  --sessionId demo-session \
  --role assistant \
  --content "Synthetic handoff evidence for the demo."

node src/cli.js distillCheckpoint \
  --scope repo \
  --scopeKey github.com/example/contextforge \
  --sessionId demo-session

node src/cli.js bootstrapContext \
  --scope repo \
  --scopeKey github.com/example/contextforge \
  --query "demo handoff" \
  --consultReason startup

All examples are synthetic. Keep .env, tokens, database files, sidecars, raw logs, and private runtime evidence out of Git.

Run As A Server Or MCP Sidecar

Local HTTP server:

node src/server.js

Local stdio MCP server:

node src/mcp.js

For a remote canonical deployment, start with the public template and follow the runtime/operations guides:

cp examples/server.env.example .env
node src/server.js

• Runtime modes
• Memory candidate lifecycle
• Operator readiness, metrics, backup, and restore
• Capability and scope authorization
• MCP profiles and context budgets

Providers And Agent Integration

Distillation providers are pluggable. The repository ships mock, codex_exec, and openai_compatible; candidate audit can use a separate execution provider. Ordinary tests fail closed before external provider execution. Live-provider tests require explicit opt-in.

CONTEXTFORGE_LIVE_TESTS=true npm run test:live

Agent adapters can ingest Codex, Claude Code, OpenCode, Grok, and Cursor CLI sessions while preserving source provenance. Start with the agent guide for bootstrap, scoped search, session IDs, and trust rules:

• Agent guide
• Copyable agent instructions
• Full CLI/provider/operator reference

Instructions For Each Repository

For a single repository, add these two lines to its AGENTS.md, replacing the example scopeKey with that repository's canonical identity:

Use ContextForge for relevant prior context at task start or resume.
Repository memory scope: scope="repo", scopeKey="github.com/owner/repo".

For several repositories in one configured workspace, keep each repository's own scopeKey and add the same workspaceKey for cross-repository context:

Use ContextForge for relevant prior context at task start or resume.
Repository memory scope: scope="repo", scopeKey="github.com/owner/product-api"; use workspaceKey="product" for cross-repository context.

Replace both example keys with your configured identities. A coordinator repository uses its own scopeKey too; member repositories do not inherit its memory scope. The workspace profile and members must already be configured; these instructions do not create them. Ordinary repo-only retrieval omits workspaceKey. Keep these instructions in each repository, not a global file with one repository's key. No tool or session procedure needs to be copied.

If an older installation still provides a contextforge-memory skill, it is optional and can be removed with that host's normal skill-management tooling.

Retrieval And Quality

Workspace profiles are explicit opt-in retrieval topology. ContextForge does not infer a workspace from the current repo scope, and creating a profile does not enable federation by itself. There is no process-global default workspace. The caller must pass workspaceKey to relevant MCP calls such as resolve_workspace, bootstrap_context, and search. Core callers use resolveWorkspace; the corresponding CLI command is workspaceResolve. bootstrapContext, search, and agentStart also accept the option on their core/CLI surfaces. Record the key in repo-local agent instructions or a wrapper configuration when it should be used consistently. Without workspaceKey, bootstrap and search retain their ordinary single-repo behavior.

• Workspace profiles and architecture
• Retrieval performance and diagnostics
• Cursor pagination contracts
• Offline memory quality evals

npm run benchmark:retrieval
npm run eval:quality

The offline quality suite uses public synthetic fixtures and isolated temporary SQLite stores. Live LLM writing quality remains a separate opt-in concern.

Development

npm run lint
npm test
npm run eval:quality
npm run verify:release

npm run lint is the hand-rolled source gate. npm run lint:eslint is a separate CI gate for undefined identifiers, unused bindings, and shadowed variables; it adds no devDependency and fetches a pinned eslint through npx, so it needs network access. Tests are organized by topic, one file per subject area, with shared helpers in test/helpers/.

npm run verify:release checks README/docs links, command references, version drift, npm package contents, and package size budgets. See Release and package policy.

Safety

• Distillation failure must not erase raw evidence.
• Checkpoints are credible handoff state, not unquestioned live truth.
• Memory candidates require review before durable promotion.
• Secrets, credentials, customer data, and private runtime evidence do not belong in committed examples, reports, or durable memory.
• Remote mode is canonical only when clients actually use the remote server; verify runtime mode before making operational claims.

License: MIT