ECF Core

Give a coding agent a source-preserving context router before it edits.

ECF Core compiles source files, docs, policies, and safe local descriptors into .ecf-core/ artifacts with exact evidence, code symbols, source-manifest facts, blocked-source proof, and an MCP server your IDE can query.

npm install -g agoragentic-ecf-core
ecf-core init .
ecf-core compile . --agent-os
ecf-core eval .
ecf-core serve-mcp .ecf-core

Expected output: .ecf-core/source-map.json, .ecf-core/source-manifest.json, .ecf-core/code-index.json, .ecf-core/context-router.json, .ecf-core/evidence-units.json, .ecf-core/policy-summary.json, .ecf-core/agent-os-import.json, and local MCP-ready context with blocked sources such as .env recorded as policy evidence instead of served as source text.

No cloud call, wallet, marketplace route, hosted runtime, or private Full ECF internals are included.

Use it when a coding agent needs to answer: what files exist, what policy applies, what source supports this answer, and what must stay blocked.

MCP quickstart:

ecf-core mcp-config --target codex . --write
ecf-core serve-mcp .ecf-core

Claude Code / Cursor-style stdio config:

{
  "mcpServers": {
    "ecf-core": {
      "command": "ecf-core",
      "args": ["serve-mcp", "/absolute/path/to/project/.ecf-core"]
    }
  }
}

Retrieval example:

ecf_core.search_context({"query":"What policy applies before editing?"})
-> source_id="docs/security.md#policy", path="docs/security.md", citation="policy-summary.json:allowed_sources[0]", policy.allowed=true

ecf_core.route_query({"query":"What code files are indexed?"})
-> route="code_symbol_lookup", file="code-index.json", results include symbols/imports with source provenance

Policy-boundary example:

ecf_core.get_policy({})
-> blocked_paths include ".env", private keys, local databases, node_modules, build output, and generated ECF artifacts

MCP registry checklist: docs/MCP_REGISTRY_CHECKLIST.md.

Agent OS preview off-ramp:

AGORAGENTIC_API_KEY=amk_your_api_key npx -y agoragentic-os preview .ecf-core/agent-os-import.json

Agoragentic family

| Repo / package | What it is | |---|---| | agoragentic-integrations | 93 public integration surfaces across frameworks, protocols, SDKs, commerce rails, and governance tools | | agoragentic-ecf-core (this repo) | Self-hosted context-governance runtime (npm agoragentic-ecf-core) | | Micro ECF | Open local context wedge (npm agoragentic-micro-ecf) | | agoragentic-premortem-golden-loop | Pre-launch release-readiness CLI (npm agoragentic-premortem-golden-loop) | | fable5-codex | Evidence-first Codex audits, reviews, fact checks, and repo sweeps | | agoragentic-summarizer-agent | Python example: route summarize via execute() | | agoragentic-openai-agents-example | OpenAI Agents SDK marketplace example |

Home: agoragentic.com · all packages: npm view <name>

Agent workflow contracts: governed agent runs and Fable review output.

Choose Your Path

| I want to… | Start here | What comes next | |---|---|---| | Set a local policy and export a small context packet | Micro ECF | Use the Micro ECF to ECF Core guide if static artifacts stop being enough. | | Run richer self-hosted context compilation, grounding evaluation, or local MCP serving | Continue with this ECF Core quick start | Keep the context runtime local; hosted deployment is not required. | | Check a governed Agent OS handoff before a hosted request | Agent OS preview handoff | Follow Agent OS import; preview is not runtime provisioning, funding, public exposure, or settlement. |

For an integration, payment, or marketplace route, use the ecosystem quick navigator.

Keep these references nearby: CLI commands, options, and exit behavior, glossary, troubleshooting, and contributing guide.

What This Means For Builders

Installing ECF Core on a codebase gives builders a self-hosted context-governance compiler. Instead of asking an AI agent to infer the whole project from chat history, builders can compile local sources into auditable artifacts that show what the agent may read, cite, summarize, and hand off to Triptych OS (Agent OS).

For day-to-day IDE work, ECF Core gives agents durable local context across sessions through ECF.md, .ecf-core/* artifacts, resident work memory, and the optional resident MCP server. The agent still needs to inspect real source files before editing, but it starts from a governed context map instead of hidden memory or stale conversation state.

Product Boundary

ECF Core is:

• local-first
• open-source
• context and policy packet generation
• source-map and citation aware
• Triptych OS (Agent OS) preview export
• useful for small builders and teams

ECF Core is not:

• hosted Agent OS
• private Full ECF
• wallet or x402 settlement
• marketplace ranking
• tenant-isolated enterprise runtime
• SOC 2 certified or audited software

Micro ECF
-> local context and policy packets for builders

ECF Core
-> open-source self-hosted context governance runtime

Triptych OS (Agent OS)
-> paid hosted deployment, runtime, budgets, APIs, receipts, marketplace access, and x402

Full ECF
-> internal/private platform engine for future high-touch dedicated deployments only

Downloadable vs Hosted

Downloadable/local in this repo:

• ECF Core context-governance runtime
• schemas, adapters, deterministic evals, evidence units, and Triptych OS (Agent OS) preview/import artifacts
• local CLI and self-hosted context-provider contracts

Hosted/private in Agoragentic:

• Triptych OS / Agent OS control plane
• Router / Marketplace ranking, matching, x402/USDC settlement, receipts, trust mutation, and reconciliation
• hosted runtime provisioning and private Full ECF internals

Self-hosting ECF Core means you own the context-governance runtime. It does not mean self-hosting the full Agoragentic control plane.

Package Family Position

Use ECF Core when static Micro ECF artifacts are not enough and you want a self-hosted context-governance compiler with local evidence, indexes, and grounding checks.

Use the other Agoragentic packages for different jobs:

| Need | Package | |---|---| | Hosted Agent OS readiness, preview, and deploy-request checks | agoragentic-os | | Router / Marketplace calls from JavaScript agents | agoragentic | | MCP-native bridge into hosted Agoragentic tools | agoragentic-mcp | | Lightweight local context packets and Harness exports | agoragentic-micro-ecf | | n8n quote, x402, execute, and receipt workflow steps | n8n-nodes-agoragentic |

ECF Core can produce Agent OS preview artifacts. It does not provide hosted wallets, settlement, public marketplace exposure, receipt issuance, or the private Full ECF runtime.

Private / Full ECF Interest

ECF Core is the public open-source layer. Full ECF is not included in this repo and is not a self-serve public SKU.

If you have a scoped private or dedicated context-governance use case and want to discuss whether Agoragentic should support it, email [email protected].

Do not treat that contact path as a SOC 2, audit, enterprise-readiness, hosted runtime, wallet, settlement, or marketplace-routing claim.

What Is Included

• Context packet schema
• Policy summary schema
• Source map schema
• Source manifest schema
• Provenance and citation contract
• Local/self-hosted context-provider boundary
• Connector adapter contracts
• Markdown/docs section adapter
• SQLite schema summary adapter
• OpenAPI summary adapter
• MCP context-provider summary adapter
• Dependency-free local compiler
• ecf-core CLI
• Deterministic eval reports
• Grounding eval loop for local fail-closed answer checks
• Semantic-lite retrieval preservation scoring
• Context Evidence Units for policy-aware, citation-backed source claims
• ECF Compile Stage readiness summaries for Agent OS preview cards
• Deterministic context compaction reports with duplicate-claim and citation-survival metrics
• Page, tree, and retrieval-plan index artifacts for local source-grounded review
• Source-manifest, code-index, and context-router artifacts for exact evidence, code-symbol lookup, deterministic stats, and semantic fallback
• Optional dependency-free ranking provider contracts (local_vector, Qdrant/Chroma precomputed results, GitNexus/code graph, MCP context provider)
• Source-preview .NET lane for C#, ASP.NET Core, EF Core, and Agent OS-ready artifact compatibility
• Deterministic compression experiment metrics
• Agent OS Harness and deployment-preview exports
• Agent OS preview/import readiness check
• Preview-only importer example for pairing Agent OS Harness evidence with a local Agoragentic Rust framework HTTP/JSON runtime
• Local stdio MCP server for active context serving from compiled artifacts
• Local resident worklog, docs-sync plan, and handoff artifacts for session continuity
• Safe examples for local projects

What Is Not Included

ECF Core does not include:

• Private Full ECF tenant-isolation internals
• Enterprise access-audit storage internals
• Customer evidence-packet automation
• Private copilot runtime
• Private connector implementations
• Hosted Agent OS provisioning
• Router ranking
• Trust/fraud scoring
• Wallet settlement
• x402 settlement execution
• Operator prompts or internal runbooks
• SOC 2 certification or audit claims

Relationship To Micro ECF

Micro ECF is the smallest local wedge: it creates durable project artifacts such as ECF.md, source maps, policy summaries, and Agent OS Harness exports.

ECF Core is the next layer up: a self-hosted context runtime for teams that want local governance, context compilation, citations, and adapter contracts without adopting Agoragentic Cloud.

Micro ECF vs ECF Core vs Triptych OS

| Layer | What It Is | When To Use It | |-------|------------|----------------| | Micro ECF | Local context wedge and durable project artifacts | You need bounded local policy, source maps, and Agent OS Harness exports. | | ECF Core | Self-hosted context-governance runtime | You need richer local compilation, evidence units, grounding evals, and provider contracts. | | Triptych OS (Agent OS) | Hosted deployment/control plane | You need hosted runtime, budgets, wallets, APIs, receipts, marketplace access, x402, and reconciliation. | | Full ECF | Private/internal platform infrastructure | Not a public self-serve SKU; reserved for Agoragentic-operated high-touch dedicated infrastructure. |

Relationship To Triptych OS (Agent OS)

Triptych OS (Agent OS) is where agents become deployed products.

Use Triptych OS (Agent OS) when you need:

• hosted runtime
• wallet budgets
• generated APIs
• receipts
• marketplace participation
• x402 monetization
• operational support

ECF Core can prepare context and policy evidence for Triptych OS (Agent OS), but it does not deploy agents or handle money.

ECF Compile Stage

ECF Core is not a generic RAG app. The default flow does not require Chroma, Pinecone, Qdrant, hosted embeddings, cloud storage, or a paid LLM API.

The compile stage turns local sources into deployment-readiness artifacts:

sources
-> source-map.json
-> source-manifest.json
-> policy-summary.json
-> evidence-units.json
-> page-index.json / tree-index.json
-> retrieval-plan.json
-> code-index.json / context-router.json
-> grounding-eval.json
-> agent-os-import.json

That answers a deployment question rather than only a retrieval question: is this context safe, cited, grounded, and ready for an owner-reviewed Agent OS preview?

Why Use ECF Core?

Use ECF Core when you want an agent to know what it can safely read, cite, summarize, and export before you deploy it into Triptych OS (Agent OS).

Before deploying an agent, compile its context boundary.

If you want the agent to run live, hold a budget, expose APIs, sell services, earn through the marketplace, or use x402 monetization, import the output into Triptych OS (Agent OS) and complete a separate owner-reviewed launch flow.

From ECF Core To Triptych OS (Agent OS)

Local flow:

ecf-core init .
ecf-core compile . --agent-os
ecf-core eval .
ecf-core eval . --grounding
ecf-core agent-os-preview .ecf-core
ecf-core validate .ecf-core

Intended Triptych OS (Agent OS) flow:

agoragentic-os preview .ecf-core/agent-os-import.json

Triptych OS (Agent OS) preview import is available through the hosted Agent OS CLI as a no-spend preview check; live deployment still requires a separate Agent OS launch flow with owner review, policy checks, runtime provisioning, and billing/spend authorization.

Current Status

ECF Core is stable open-source software for local and self-hosted context governance.

The stable 1.0 surface includes:

1. schemas
2. local examples
3. adapter contracts
4. basic context compiler
5. deterministic tests
6. local CLI
7. deterministic eval reports
8. Agent OS preview/import artifacts

The 1.1 surface adds deterministic semantic-lite ranking, compression experiment metrics, an Agent OS preview-import check, and real-world example fixtures.

The 1.2 surface adds the local grounding eval loop and durable LLM handoff guidance through ECF.md.

The 1.3 surface adds optional dependency-free ranking provider contracts: built-in local_vector scoring plus precomputed-result hooks for Qdrant, Chroma, GitNexus/code graph, and MCP context providers.

The 1.4 surface adds local page/tree context index artifacts and retrieval-plan metadata for Agent OS preview readiness. It does not add OCR/VLM dependencies, hosted RAG, vector databases, wallet settlement, marketplace routing, or Full ECF internals.

The current compile surface also adds source-manifest.json, code-index.json, and context-router.json so coding agents can route questions to exact evidence, policy lookup, code-symbol lookup, deterministic source stats, or semantic summaries without treating larger context as the answer.

The compile-stage surface now also emits evidence-units.json as the clean Agent OS-facing evidence artifact while retaining context-evidence-units.json for compatibility with earlier consumers.

The .NET source-preview lane adds artifact-compatible C#, ASP.NET Core, and EF Core scanners plus an ecfnet CLI scaffold. It is local/previews-only and does not include Full ECF, hosted Agent OS runtime, wallets, x402 execution, marketplace routing, or enterprise audit internals.

Do not copy the private agoragentic-enterprise/ runtime into this repo.

Install

Install from npm:

npm install -g agoragentic-ecf-core

Or run the published package directly with npx:

npx agoragentic-ecf-core init .
npx agoragentic-ecf-core compile . --agent-os

GitHub install also works:

npm install -g github:rhein1/agoragentic-ecf-core

Quick Start

ecf-core init .
ecf-core compile . --agent-os
ecf-core eval .
ecf-core agent-os-preview .ecf-core
ecf-core validate .ecf-core

Optional resident continuity:

ecf-core worklog begin . --goal "current goal"
ecf-core worklog checkpoint . --summary "what changed"
ecf-core worklog status .
ecf-core docs-sync plan .
ecf-core handoff . --write

Use this before closing a long IDE/Codex session or after a scoped commit. The resident artifacts make the next session explicit: what was done, what remains unfinished, which docs may need updates, and what prompt should continue the work.

The compiler writes:

.ecf-core/
  context-packet.json
  source-map.json
  source-manifest.json
  policy-summary.json
  evidence-units.json
  context-evidence-units.json
  context-compaction-report.json
  page-index.json
  tree-index.json
  retrieval-plan.json
  code-index.json
  context-router.json
  manifest.json
  deployment-preview.json
  agent-os-harness.json
  agent-os-handoff.json
  agent-os-import.json
  eval-report.json
  eval-report.md
  grounding-eval.json
  grounding-eval.md
  worklog/current.json
  worklog/history.jsonl
  worklog/checkpoints.jsonl
  worklog/latest-summary.md
  docs-sync-plan.json
  handoff.json
  handoff.md
  next-session.md

Review ecf.config.json before compiling sensitive repositories.

Run ecf-core eval --grounding, ecf-core agent-os-preview, and ecf-core validate before importing artifacts into Triptych OS (Agent OS) preview.

Grounding Eval Loop

ECF Core tests whether your local context can safely support agent answers before deployment.

Run:

ecf-core eval . --grounding

The loop is local and fail-closed:

eval query
  |
  v
retrieve allowed sources
  |
  v
synthesize extractive answer
  |
  v
grounded?
  |-- yes -> pass with citation evidence
  |
  |-- no -> rewrite query -> retry
                         |
                         v
              still unsupported?
                         |
                         v
       "I don't know based on the allowed context."

This is not a hosted RAG system and does not require Chroma, Qdrant, LangGraph, Groq, embeddings, or any paid LLM API by default. It retrieves from the compiled context packet, blocks disallowed sources, checks citation support, rewrites unsupported queries, retries within the configured limit, and fails closed when the project does not contain enough evidence.

Triptych OS (Agent OS) can use grounding-eval.json as preview evidence when deciding whether a deployment has enough context to launch safely. Live deployment, runtime provisioning, wallet funding, marketplace publication, x402 exposure, and Full ECF access remain separate owner-reviewed Agent OS flows.

Context Evidence Units

ECF Core emits deterministic Context Evidence Units during compile:

.ecf-core/evidence-units.json
.ecf-core/context-evidence-units.json
.ecf-core/context-compaction-report.json

evidence-units.json is the current compile-stage artifact for Agent OS preview. context-evidence-units.json remains as a compatibility alias. These files convert allowed sources into citation-backed claims plus policy flags for Agent OS preview. They help identify duplicate claims, repeated boilerplate, citation survival, retrieval preservation, and compression ratio without adding external vector databases, hosted LLMs, wallet settlement, marketplace routing, or Full ECF internals.

Context Index Artifacts

ECF Core also emits deterministic local context indexes:

.ecf-core/page-index.json
.ecf-core/tree-index.json
.ecf-core/retrieval-plan.json

These artifacts preserve document, page, section, and tree-node structure where the baseline adapters can detect it. Markdown headings, text summaries, OpenAPI summaries, SQLite summaries, and MCP context summaries become index nodes with policy flags and citations. PDF/image indexing is represented as a disabled adapter contract in V1; ECF Core does not ship OCR, VLM, hosted RAG, or vector database dependencies by default.

Triptych OS (Agent OS) preview import can use these files to show context index readiness, unsupported grounding questions, and sources requiring owner review before any public exposure. Live deployment remains a separate owner-reviewed Agent OS flow.

Source Manifest, Code Index, And Context Router

ECF Core does not rely on larger prompts as the retrieval strategy. Compile emits:

.ecf-core/source-manifest.json
.ecf-core/code-index.json
.ecf-core/context-router.json

source-manifest.json records included, blocked, review-required, and generated-excluded source facts without copying blocked raw content. code-index.json records dependency-free symbols, imports, and entrypoint hints for indexed code files. context-router.json declares the local route order: exact text lookup, policy lookup, code-symbol lookup, source-manifest query, deterministic stats, then semantic summary fallback.

Use ecf_core.route_query over MCP when a coding agent should choose the right local artifact instead of stuffing all context into a prompt.

Optional external code-graph tools such as Gortex can be evaluated as adapters later. Treat them as source-index providers that may enrich code-index.json or context-router.json; do not make them a required dependency until the local first-run artifact is already useful.

CLI

ecf-core init [project] [--force]
ecf-core compile [project] [--config ecf.config.json] [--out .ecf-core] [--json] [--agent-os]
ecf-core eval [project] [--config ecf.config.json] [--out .ecf-core] [--json] [--grounding]
ecf-core agent-os-preview [artifact-dir] [--json]
ecf-core status [project] [--out .ecf-core] [--write] [--json]
ecf-core context-pack [project] [--out .ecf-core] [--task "current task"] [--write] [--json]
ecf-core worklog begin [project] --goal "goal"
ecf-core worklog checkpoint [project] --summary "summary"
ecf-core worklog finish [project] --summary "summary" [--commit abc] [--tests "npm test"]
ecf-core worklog status [project] [--json]
ecf-core docs-sync plan [project] [--out .ecf-core] [--json]
ecf-core handoff [project] [--out .ecf-core] [--write] [--json]
ecf-core mcp-config --target codex [project] [--out .ecf-core] [--write] [--install-codex]
ecf-core serve-mcp [artifact-dir]
ecf-core validate [artifact-dir]
ecf-core version

ECF Core intentionally does not expose a micro-ecf executable. Use the separate agoragentic-micro-ecf package when you want the lightweight Micro ECF local wedge.

Paste Into Your IDE LLM

For a durable assistant handoff, point the IDE assistant at ECF.md first.

Install ECF Core from https://github.com/rhein1/agoragentic-ecf-core for this local repo.

Before installing, explain what it will do, what files it will create, what it blocks by default, and that it does not deploy agents, handle wallets, or include Full ECF private internals.

Only proceed after I approve.

After approval, install it, run ecf-core init, show me ecf.config.json for review, then run ecf-core compile --agent-os, ecf-core eval --grounding, ecf-core agent-os-preview, and ecf-core validate.

Development

npm test
npm run check
npm run pack:dry

Docs

• Install
• CLI Reference
• Glossary
• Troubleshooting
• Agent Workflow Contracts
• Fable Review Contract
• Adapter Contracts
• Custom Adapters
• Evaluation
• Local MCP Server
• MCP Registry Checklist
• Resident Work Memory
• Context Evidence Units
• Source Manifest, Code Index, And Context Router
• .NET Support
• Versioning
• Docs Index
• Agent OS Import Contract
• Durable LLM Handoff
• Workflow Examples
• Example Output
• Real-World Examples
• LLM-Assisted Install
• Repository Images
• Release Checklist
• npm Trusted Publishing

License

Apache-2.0.